Fix most doxygen warnings in code comments

Sming/Arch/Esp8266/Components/gdbstub/GdbPacket.h

@@ -82,9 +82,9 @@ class GdbPacket
 
 	/** @brief Encode a value as hex characters, LSB first
 	 *  @param dst Location for output, will NOT be nul-terminated
-	 *  @param srcData Data bytes to encode
+	 *  @param src Data bytes to encode
 	 *  @param size Size of source data in bytes
-	 *  @Note destination buffer must have enough space for (size * 2) chars
+	 *  @note destination buffer must have enough space for (size * 2) chars
 	 */
 	static void encodeHexBlock(char* dst, const void* src, size_t size);
 

Sming/Arch/Esp8266/Components/spi_flash/include/esp_spi_flash.h

@@ -17,12 +17,13 @@ extern "C" {
 
 #include <user_config.h>
 
-// Flash memory access must be aligned and in multiples of 4-byte words
+/// Flash memory access must be aligned and in multiples of 4-byte words
 #define INTERNAL_FLASH_WRITE_UNIT_SIZE 4
 #define INTERNAL_FLASH_READ_UNIT_SIZE 4
 
 #define FLASH_TOTAL_SEC_COUNT (flashmem_get_size_sectors())
 
+/// Number of flash sectors reserved for system parameters at start
 #define SYS_PARAM_SEC_COUNT 4
 #define FLASH_WORK_SEC_COUNT (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)
 
@@ -61,10 +62,10 @@ typedef struct
 	} size : 4;
 } STORE_TYPEDEF_ATTR SPIFlashInfo;
 
-/** @brief obtain the flash memory address for a memory pointer
+/** @brief Obtain the flash memory address for a memory pointer
  *  @param memptr
- *  @retval uint32_t offset from start of flash memory
- *  @note if memptr is not in valid flash memory it will return an offset which exceeds
+ *  @retval uint32_t Offset from start of flash memory
+ *  @note If memptr is not in valid flash memory it will return an offset which exceeds
  *  the internal flash memory size. This is caught by constructors using getMaxSize()
  *  to provide a zero-length extent.
  */
@@ -73,20 +74,20 @@ static inline uint32_t flashmem_get_address(const void* memptr)
 	return (uint32_t)memptr - INTERNAL_FLASH_START_ADDRESS;
 }
 
-/** @brief write a block of data to flash
- *  @param from buffer to obtain data from
- *  @param toaddr flash location to start writing
- *  @param size number of bytes to write
- *  @retval uint32_t number of bytes written
- *  @note none of the parameters need to be aligned
+/** @brief Write a block of data to flash
+ *  @param from Buffer to obtain data from
+ *  @param toaddr Flash location to start writing
+ *  @param size Number of bytes to write
+ *  @retval uint32_t Number of bytes written
+ *  @note None of the parameters need to be aligned
  */
 uint32_t flashmem_write(const void* from, uint32_t toaddr, uint32_t size);
 
-/** @brief read a block of data from flash
- *  @param to buffer to store data
- *  @param fromaddr flash location to start reading
- *  @param size number of bytes to read
- *  @retval uint32_t number of bytes written
+/** @brief Read a block of data from flash
+ *  @param to Buffer to store data
+ *  @param fromaddr Flash location to start reading
+ *  @param size Number of bytes to read
+ *  @retval uint32_t Number of bytes written
  *  @note none of the parameters need to be aligned
  */
 uint32_t flashmem_read(void* to, uint32_t fromaddr, uint32_t size);
@@ -97,61 +98,62 @@ uint32_t flashmem_read(void* to, uint32_t fromaddr, uint32_t size);
  */
 bool flashmem_erase_sector(uint32_t sector_id);
 
-/** @brief get flash memory information block
- *  @retval SPIFlashInfo information block
+/** @brief Get flash memory information block
+ *  @retval SPIFlashInfo Information block
  */
 SPIFlashInfo flashmem_get_info();
 
 /** @brief Returns a number indicating the size of flash memory chip
- *  @retval see SpiFlashInfo.size field for possible values
+ *  @retval uint8_t See SpiFlashInfo.size field for possible values
  */
 uint8_t flashmem_get_size_type();
 
 /** @brief get the total flash memory size
- *  @retval uint32_t size in bytes
+ *  @retval uint32_t Size in bytes
  */
 uint32_t flashmem_get_size_bytes();
 
-/** @brief get the total number of flash sectors
- *  @retval uint16_t sector count
+/** @brief Get the total number of flash sectors
+ *  @retval uint16_t Sector count
  */
 uint16_t flashmem_get_size_sectors();
 
 /** @brief Helper function: find the flash sector in which an address resides
  *  @param address
- *  @param pstart OUT/OPTIONAL: start of sector containing the given address
- *  @param pend OUT/OPTIONAL: last address in sector
- *  @retval uint32_t sector number for the given address
- *  @note optional parameters may be null
+ *  @param pstart OUT/OPTIONAL: Start of sector containing the given address
+ *  @param pend OUT/OPTIONAL: Last address in sector
+ *  @retval uint32_t Sector number for the given address
+ *  @note Optional parameters may be null
  */
 uint32_t flashmem_find_sector(uint32_t address, uint32_t* pstart, uint32_t* pend);
 
 /** @brief Get sector number containing the given address
+ *  @param addr
  *  @retval uint32_t sector number
  */
 uint32_t flashmem_get_sector_of_address(uint32_t addr);
 
 /** @brief write to flash memory
- *  @param to buffer to read data from - MUST be word-aligned
- *  @param toaddr flash address (offset) to write to - MUST be word-aligned
- *  @param size number of bytes to write - MUST be word-aligned
- *  @retval number of bytes actually written
+ *  @param from Buffer to read data from - MUST be word-aligned
+ *  @param toaddr Flash address (offset) to write to - MUST be word-aligned
+ *  @param size Number of bytes to write - MUST be word-aligned
+ *  @retval uint32_t Number of bytes actually written
  *  @note All parameters MUST be aligned to 4-byte word boundaries, **including** the RAM pointer
  */
 uint32_t flashmem_write_internal(const void* from, uint32_t toaddr, uint32_t size);
 
-/** @brief read from flash memory
- *  @param to buffer to store data - MUST be word-aligned
- *  @param fromaddr flash address (offset) to read from - MUST be word-aligned
- *  @param size number of bytes to read - MUST be word-aligned
- *  @retval number of bytes actually read
+/** @brief Read from flash memory
+ *  @param to Buffer to store data - MUST be word-aligned
+ *  @param fromaddr Flash address (offset) to read from - MUST be word-aligned
+ *  @param size Number of bytes to read - MUST be word-aligned
+ *  @retval uint32_t Number of bytes actually read
  *  @note All parameters MUST be aligned to 4-byte word boundaries, **including** the RAM pointer
  */
 uint32_t flashmem_read_internal(void* to, uint32_t fromaddr, uint32_t size);
 
 /*
  * @brief Returns the address of the first free block on flash
- * @retval  uint32_t the actual address on flash
+ * @retval  uint32_t The actual address on flash
  */
 uint32_t flashmem_get_first_free_block_address();
 

Sming/Core/AtClient.h

@@ -8,8 +8,8 @@
  *
  ****/
 
-/**	@defgroup serial AtCommand serial
- *	@brief	Asynchronous AT command client
+/**	@ingroup serial
+ *	@brief Asynchronous AT command client
  *  @{
  */
 
@@ -59,29 +59,29 @@ class AtClient
 
 	/**
 	 * @brief Sends AT command
-	 * @param text String The actual AT command text. For example AT+CAMSTOP
-	 * @param altResponse String Expected response on success in addition to the default one which is OK
-	 * @param timeoutMs uint32_t Time in milliseconds to wait for response
-	 * @param retries unsigned Retries on error
+	 * @param text The actual AT command text. For example AT+CAMSTOP
+	 * @param altResponse Expected response on success in addition to the default one which is OK
+	 * @param timeoutMs Time in milliseconds to wait for response
+	 * @param retries Retries on error
 	 */
 	void send(const String& text, const String& altResponse = nullptr, uint32_t timeoutMs = AT_TIMEOUT,
 			  unsigned retries = 0);
 
 	/**
 	 * @brief Sends AT command
-	 * @param text String The actual AT command text. For example AT+CAMSTOP
-	 * @param AtReceiveCallback onReceive
-	 * @param timeoutMs uint32_t Time in milliseconds to wait for response
-	 * @param retries int Retries on error
+	 * @param text The actual AT command text. For example AT+CAMSTOP
+	 * @param onReceive
+	 * @param timeoutMs Time in milliseconds to wait for response
+	 * @param retries Retries on error
 	 */
 	void send(const String& text, AtReceiveCallback onReceive, uint32_t timeoutMs = AT_TIMEOUT, unsigned retries = 0);
 
 	/**
 	 * @brief Sends AT command
 	 * @param text String The actual AT command text. For example AT+CAMSTOP
-	 * @param AtCompleteCallback onComplete
-	 * @param timeoutMs uint32_t Time in milliseconds to wait for response
-	 * @param retries int Retries on error
+	 * @param onComplete
+	 * @param timeoutMs Time in milliseconds to wait for response
+	 * @param retries Retries on error
 	 */
 	void send(const String& text, AtCompleteCallback onComplete, uint32_t timeoutMs = AT_TIMEOUT, unsigned retries = 0);
 
@@ -91,19 +91,19 @@ class AtClient
 	 * @brief Adds a command to the queue.
 	 * 		  If you need all the flexibility then use that command
 	 * 		  and manually set your AtCommand arguments.
-	 * @param command AtCommand
+	 * @param command
 	 */
 	void send(AtCommand command);
 
 	/**
 	 * @brief Executes directly (does not queue it) a command
-	 * @param command AtCommand
+	 * @param command
 	 */
 	void sendDirect(AtCommand command);
 
 	/**
 	 * @brief Returns the current state
-	 * @return AtState
+	 * @retval AtState
 	 */
 	AtState getState()
 	{

Sming/Core/Data/Buffer/CircularBuffer.h

@@ -86,7 +86,7 @@ class CircularBuffer : public ReadWriteStream
 	size_t write(uint8_t charToWrite) override;
 
 	/** @brief  Write chars to stream
-     *  @param  buffer Pointer to buffer to write to the stream
+     *  @param  data Pointer to buffer to write to the stream
      *  @param  size Quantity of chars to writen
      *  @retval size_t Quantity of chars written to stream
      */

Sming/Core/Data/MailMessage.h

@@ -38,36 +38,58 @@ class MailMessage
 	String subject;
 	String cc;
 
+	/**
+	 * @brief Set a header value
+	 * @param name
+	 * @param value
+	 * @retval MailMessage&
+	 */
 	MailMessage& setHeader(const String& name, const String& value);
 
+	/**
+	 * @brief Get a reference to the current set of headers
+	 * @retval HttpHeaders&
+	 */
 	HttpHeaders& getHeaders();
 
 	/**
 	 * @brief Sets the body of the email
-	 * @param String body
-	 * @param MimeType mime
+	 * @param body
+	 * @param mime
+	 * @retval MailMessage&
 	 */
 	MailMessage& setBody(const String& body, MimeType mime = MIME_TEXT);
 
 	/**
 	 * @brief Sets the body of the email
-	 * @param Stream& stream
-	 * @param MimeType mime
+	 * @param stream
+	 * @param mime
+	 * @retval MailMessage&
 	 */
 	MailMessage& setBody(IDataSourceStream* stream, MimeType mime = MIME_TEXT);
 
 	/**
 	 * @brief Adds attachment to the email
+	 * @param stream
+	 * @retval MailMessage&
 	 */
 	MailMessage& addAttachment(FileStream* stream);
 
 	/**
 	 * @brief Adds attachment to the email
+	 * @param stream
+	 * @param mime
+	 * @param filename
+	 * @retval MailMessage&
 	 */
 	MailMessage& addAttachment(IDataSourceStream* stream, MimeType mime, const String& filename = "");
 
 	/**
 	 * @brief Adds attachment to the email
+	 * @param stream
+	 * @param mime
+	 * @param filename
+	 * @retval MailMessage&
 	 */
 	MailMessage& addAttachment(IDataSourceStream* stream, const String& mime, const String& filename = "");
 

Sming/Core/Data/Stream/FileStream.h

@@ -29,6 +29,7 @@ class FileStream : public ReadWriteStream
 
 	/** @brief  Create a file stream
      *  @param  fileName Name of file to open
+     *  @param	openFlags
      */
 	FileStream(const String& fileName, FileOpenFlags openFlags = eFO_ReadOnly)
 	{

Sming/Core/Data/Stream/GdbFileStream.h

@@ -26,6 +26,7 @@ class GdbFileStream : public ReadWriteStream
 
 	/** @brief  Create a file stream
      *  @param  fileName Name of file to open
+     *  @param	openFlags
      */
 	GdbFileStream(const String& fileName, FileOpenFlags openFlags = eFO_ReadOnly)
 	{

Sming/Core/Data/Stream/TemplateFileStream.h

@@ -24,7 +24,7 @@ class TemplateFileStream : public TemplateStream
 {
 public:
 	/** @brief Create a template file stream
-     *  @param  templateFileName Template filename
+     *  @param  fileName Template filename
      */
 	TemplateFileStream(const String& fileName) : TemplateStream(new FileStream(fileName))
 	{

Sming/Core/Data/StreamTransformer.h

@@ -23,7 +23,7 @@
 
 /**
  * @brief Callback specification for the stream transformers
- * @note See StreamTransformer::transform() method for details
+ * @see See `StreamTransformer::transform()` method for details
  */
 typedef Delegate<size_t(const uint8_t* in, size_t inLength, uint8_t* out, size_t outLength)> StreamTransformerCallback;
 
@@ -92,10 +92,10 @@ class StreamTransformer : public IDataSourceStream
 protected:
 	/**
 	 * @brief Inherited class implements this method to transform a block of data
-	 * @param const uint8_t* in source data
-	 * @param size_t inLength source data length
-	 * @param uint8_t* out output buffer
-	 * @param size_t outLength size of output buffer
+	 * @param in source data
+	 * @param inLength source data length
+	 * @param out output buffer
+	 * @param outLength size of output buffer
 	 * @retval size_t number of output bytes written
 	 * @note Called with `in = nullptr` and `inLength = 0` at end of input stream
 	 */

Sming/Core/DateTime.h

@@ -106,6 +106,7 @@ class DateTime
 	/** @brief  Set time using time and date component values
 	 *  @param  sec Seconds
 	 *  @param  min Minutes
+	 *  @param  hour Hour
 	 *  @param  day Day of month
 	 *  @param  month Month (0=Jan, 11=Dec)
 	 *  @param  year Year

Sming/Core/HardwarePWM.h

@@ -55,7 +55,7 @@ class HardwarePWM
 	}
 
 	/** @brief  Set PWM duty cycle for a channel
-     *  @param  channel Channel to set
+     *  @param  chan Channel to set
      *  @param  duty Value of duty cycle to set channel to
      *  @param  update Update PWM output
      *  @retval bool True on success