Merge pull request #4450 from deepikabhavnani/doxygen-template

Doxygen template

drivers/AnalogOut.h

@@ -103,6 +103,7 @@ public:
     }
 
     /** An operator shorthand for write()
+     * \sa AnalogOut::write()
      */
     AnalogOut& operator= (float percent) {
         // Underlying write call is thread safe
@@ -110,6 +111,9 @@ public:
         return *this;
     }
 
+    /** An operator shorthand for write()
+     * \sa AnalogOut::write()
+     */
     AnalogOut& operator= (AnalogOut& rhs) {
         // Underlying write call is thread safe
         write(rhs.read());
@@ -117,6 +121,7 @@ public:
     }
 
     /** An operator shorthand for read()
+     * \sa AnalogOut::read()
      */
     operator float() {
         // Underlying read call is thread safe

drivers/BusIn.h

@@ -95,10 +95,12 @@ public:
     }
 
     /** A shorthand for read()
+     *  \sa DigitalIn::read()
      */
     operator int();
 
     /** Access to particular bit in random-iterator fashion
+     * @param index  Position of bit
      */
     DigitalIn & operator[] (int index);
 

drivers/BusInOut.h

@@ -108,15 +108,18 @@ public:
     }
 
      /** A shorthand for write()
-     */
+    * \sa BusInOut::write()
+      */
     BusInOut& operator= (int v);
     BusInOut& operator= (BusInOut& rhs);
 
     /** Access to particular bit in random-iterator fashion
-    */
+     * @param index  Bit Position
+     */
     DigitalInOut& operator[] (int index);
 
     /** A shorthand for read()
+     * \sa BusInOut::read()
      */
     operator int();
 

drivers/BusOut.h

@@ -92,15 +92,18 @@ public:
     }
 
     /** A shorthand for write()
+     * \sa BusOut::write()
      */
     BusOut& operator= (int v);
     BusOut& operator= (BusOut& rhs);
 
     /** Access to particular bit in random-iterator fashion
+     * @param index  Bit Position
      */
     DigitalOut& operator[] (int index);
 
     /** A shorthand for read()
+     * \sa BusOut::read()
      */
     operator int();
 

drivers/CAN.h

@@ -46,6 +46,12 @@ public:
     }
 
     /** Creates CAN message with specific content.
+     *
+     *  @param _id      Message ID
+     *  @param _data    Mesaage Data
+     *  @param _len     Message Data length
+     *  @param _type    Type of Data: Use enum CANType for valid parameter values
+     *  @param _format  Data Format: Use enum CANFormat for valid parameter values
      */
     CANMessage(int _id, const char *_data, char _len = 8, CANType _type = CANData, CANFormat _format = CANStandard) {
       len    = _len & 0xF;
@@ -56,6 +62,9 @@ public:
     }
 
     /** Creates CAN remote message.
+     *
+     *  @param _id      Message ID
+     *  @param _format  Data Format: Use enum CANType for valid parameter values
      */
     CANMessage(int _id, CANFormat _format = CANStandard) {
       len    = 0;
@@ -197,11 +206,15 @@ public:
      */
     int filter(unsigned int id, unsigned int mask, CANFormat format = CANAny, int handle = 0);
 
-    /** Returns number of read errors to detect read overflow errors.
+    /**  Detects read errors - Used to detect read overflow errors.
+     *
+     *  @returns number of read errors
      */
     unsigned char rderror();
 
-    /** Returns number of write errors to detect write overflow errors.
+    /** Detects write errors - Used to detect write overflow errors.
+     *
+     *  @returns number of write errors
      */
     unsigned char tderror();
 

drivers/DigitalIn.h

@@ -102,6 +102,7 @@ public:
     }
 
     /** An operator shorthand for read()
+     * \sa DigitalIn::read()
      */
     operator int() {
         // Underlying read is thread safe

drivers/DigitalInOut.h

@@ -112,6 +112,7 @@ public:
     }
 
     /** A shorthand for write()
+     * \sa DigitalInOut::write()
      */
     DigitalInOut& operator= (int value) {
         // Underlying write is thread safe
@@ -119,6 +120,9 @@ public:
         return *this;
     }
 
+    /** A shorthand for write()
+     * \sa DigitalInOut::write()
+     */
     DigitalInOut& operator= (DigitalInOut& rhs) {
         core_util_critical_section_enter();
         write(rhs.read());
@@ -127,6 +131,7 @@ public:
     }
 
     /** A shorthand for read()
+     * \sa DigitalInOut::read()
      */
     operator int() {
         // Underlying call is thread safe

drivers/DigitalOut.h

@@ -98,6 +98,7 @@ public:
     }
 
     /** A shorthand for write()
+     * \sa DigitalOut::write()
      */
     DigitalOut& operator= (int value) {
         // Underlying write is thread safe
@@ -105,6 +106,9 @@ public:
         return *this;
     }
 
+    /** A shorthand for write()
+     * \sa DigitalOut::write()
+     */
     DigitalOut& operator= (DigitalOut& rhs) {
         core_util_critical_section_enter();
         write(rhs.read());
@@ -113,6 +117,7 @@ public:
     }
 
     /** A shorthand for read()
+     * \sa DigitalOut::read()
      */
     operator int() {
         // Underlying call is thread safe

drivers/Ethernet.h

@@ -111,15 +111,16 @@ public:
 
     /** Read from an recevied ethernet packet.
      *
-     *  After receive returnd a number bigger than 0it is
+     *  After receive returned a number bigger than 0 it is
      *  possible to read bytes from this packet.
-     *  Read will write up to size bytes into data.
      *
-     *  It is possible to use read multible times.
+     *  @param data      Pointer to data packet
+     *  @param size      Size of data to be read.
+     *  @returns         The number of byte read.
+     *
+     *  @note It is possible to use read multiple times.
      *  Each time read will start reading after the last read byte before.
      *
-     *  @returns
-     *  The number of byte read.
      */
     int read(char *data, int size);
 

drivers/InterruptManager.h

@@ -55,7 +55,9 @@ namespace mbed {
  */
 class InterruptManager {
 public:
-    /** Return the only instance of this class
+    /** Get the instance of InterruptManager Class
+     *
+     *  @return the only instance of this class
      */
     static InterruptManager* get();
 

drivers/PortInOut.h

@@ -89,18 +89,23 @@ public:
     }
 
     /** A shorthand for write()
+     * \sa PortInOut::write()
      */
     PortInOut& operator= (int value) {
         write(value);
         return *this;
     }
 
+    /** A shorthand for write()
+     * \sa PortInOut::write()
+     */
     PortInOut& operator= (PortInOut& rhs) {
         write(rhs.read());
         return *this;
     }
 
     /** A shorthand for read()
+     * \sa PortInOut::read()
      */
     operator int() {
         return read();

drivers/PortOut.h

@@ -83,18 +83,23 @@ public:
     }
 
     /** A shorthand for write()
+     * \sa PortOut::write()
      */
     PortOut& operator= (int value) {
         write(value);
         return *this;
     }
 
+    /** A shorthand for read()
+     * \sa PortOut::read()
+     */
     PortOut& operator= (PortOut& rhs) {
         write(rhs.read());
         return *this;
     }
 
     /** A shorthand for read()
+     * \sa PortOut::read()
      */
     operator int() {
         return read();

drivers/PwmOut.h

@@ -151,6 +151,7 @@ public:
     }
 
     /** A operator shorthand for write()
+     *  \sa PwmOut::write()
      */
     PwmOut& operator= (float value) {
         // Underlying call is thread safe
@@ -159,6 +160,7 @@ public:
     }
 
     /** A operator shorthand for write()
+     * \sa PwmOut::write()
      */    
     PwmOut& operator= (PwmOut& rhs) {
         // Underlying call is thread safe
@@ -167,6 +169,7 @@ public:
     }
 
     /** An operator shorthand for read()
+     * \sa PwmOut::read()
      */
     operator float() {
         // Underlying call is thread safe

drivers/Timer.h

@@ -67,14 +67,20 @@ public:
     void reset();
 
     /** Get the time passed in seconds
+     *
+     *  @returns    Time passed in seconds
      */
     float read();
 
-    /** Get the time passed in mili-seconds
+    /** Get the time passed in milli-seconds
+     *
+     *  @returns    Time passed in milli seconds
      */
     int read_ms();
 
     /** Get the time passed in micro-seconds
+     *
+     *  @returns    Time passed in micro seconds
      */
     int read_us();
 

drivers/TimerEvent.h

@@ -33,6 +33,8 @@ public:
     TimerEvent(const ticker_data_t *data);
 
     /** The handler registered with the underlying timer interrupt
+     *
+     *  @param id       Timer Event ID
      */
     static void irq(uint32_t id);
 

features/filesystem/Dir.h

@@ -58,13 +58,12 @@ public:
 
     /** Close a directory
      *
-     *  return          0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure
      */
     virtual int close();
 
     /** Read the next directory entry
      *
-     *  @param path     The buffer to read the null terminated path name in to
      *  @param ent      The directory entry to fill out
      *  @return         1 on reading a filename, 0 at end of directory, negative error on failure
      */

features/filesystem/FileSystem.h

@@ -44,11 +44,13 @@ class File;
  *  Implementations must provide at minimum file operations and mount
  *  operations for block devices.
  *
- *  @Note Synchronization level: Set by subclass
+ * @note Synchronization level: Set by subclass
  */
 class FileSystem : public FileSystemLike {
 public:
     /** FileSystem lifetime
+     *
+     *  @param name       Name to add filesystem to tree as
      */
     FileSystem(const char *name = NULL);
     virtual ~FileSystem() {}
@@ -114,7 +116,7 @@ protected:
     /** Close a file
      *
      *  @param file     File handle
-     *  return          0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure
      */
     virtual int file_close(fs_file_t file) = 0;
 
@@ -195,7 +197,7 @@ protected:
     /** Close a directory
      *
      *  @param dir      Dir handle
-     *  return          0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure
      */
     virtual int dir_close(fs_dir_t dir);
 

features/filesystem/bd/ChainingBlockDevice.h

@@ -43,21 +43,22 @@
  *  // contains 96 blocks of size 512 bytes
  *  BlockDevice *bds[] = {&mem1, &mem2};
  *  ChainingBlockDevice chainmem(bds);
+ *  @endcode
  */
 class ChainingBlockDevice : public BlockDevice
 {
 public:
     /** Lifetime of the memory block device
      *
-     *  @param bds      Array of block devices to chain with sequential block addresses
-     *  @param count    Number of block devices to chain
+     *  @param bds         Array of block devices to chain with sequential block addresses
+     *  @param bd_count    Number of block devices to chain
      *  @note All block devices must have the same block size
      */
     ChainingBlockDevice(BlockDevice **bds, size_t bd_count);
 
     /** Lifetime of the memory block device
      *
-     *  @param bds      Array of block devices to chain with sequential block addresses
+     *  @param bds          Array of block devices to chain with sequential block addresses
      *  @note All block devices must have the same block size
      */
     template <size_t Size>
@@ -69,8 +70,6 @@ public:
 
     /** Lifetime of the memory block device
      *
-     *  @param bds      Array of block devices to chain with sequential block addresses
-     *  @note All block devices must have the same block size
      */
     virtual ~ChainingBlockDevice() {}
 

features/filesystem/bd/HeapBlockDevice.h

@@ -44,14 +44,25 @@
  *     printf("%s", block);
  *     bd.deinit();
  * }
+ * @endcode
  */
 class HeapBlockDevice : public BlockDevice
 {
 public:
 
     /** Lifetime of the memory block device
+     *
+     * @param size      Size of the Block Device in bytes
+     * @param block     Block size in bytes
      */
     HeapBlockDevice(bd_size_t size, bd_size_t block=512);
+    /** Lifetime of the memory block device
+     *
+     * @param size      Size of the Block Device in bytes
+     * @param read      Minimum read size required in bytes
+     * @param program   Minimum program size required in bytes
+     * @param erase     Minimum erase size required in bytes
+     */
     HeapBlockDevice(bd_size_t size, bd_size_t read, bd_size_t program, bd_size_t erase);
     virtual ~HeapBlockDevice();
 

features/filesystem/bd/SlicingBlockDevice.h

@@ -44,6 +44,7 @@
  *
  *  // Create a block device that maps to the middle 32 blocks
  *  SlicingBlockDevice slice3(&mem, 16*512, -16*512);
+ * @endcode
  */
 class SlicingBlockDevice : public BlockDevice
 {
@@ -62,7 +63,7 @@ public:
      *  @param bd       Block device to back the SlicingBlockDevice
      *  @param start    Start block address to map to block 0, negative addresses
      *                  are calculated from the end of the underlying block device
-     *  @param stop     End block address to mark the end of the block device,
+     *  @param end      End block address to mark the end of the block device,
      *                  this block is not mapped, negative addresses are
      *                  calculated from the end of the underlying block device
      */

features/filesystem/fat/FATFileSystem.h

@@ -57,6 +57,8 @@ public:
      *    volume and upto 16MiB for exFAT volume. If zero is given,
      *    the default allocation unit size is selected by the underlying
      *    filesystem, which depends on the volume size.
+     *   
+     *  @return         0 on success, negative error code on failure
      */
     static int format(BlockDevice *bd, int allocation_unit = 0);
 
@@ -126,7 +128,7 @@ protected:
     /** Close a file
      *
      *  @param file     File handle
-     *  return          0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure
      */
     virtual int file_close(fs_file_t file);
 
@@ -134,7 +136,7 @@ protected:
      *
      *  @param file     File handle
      *  @param buffer   The buffer to read in to
-     *  @param size     The number of bytes to read
+     *  @param len      The number of bytes to read
      *  @return         The number of bytes read, 0 at end of file, negative error on failure
      */
     virtual ssize_t file_read(fs_file_t file, void *buffer, size_t len);
@@ -143,7 +145,7 @@ protected:
      *
      *  @param file     File handle
      *  @param buffer   The buffer to write from
-     *  @param size     The number of bytes to write 
+     *  @param len      The number of bytes to write 
      *  @return         The number of bytes written, negative error on failure
      */
     virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t len);
@@ -192,7 +194,7 @@ protected:
     /** Close a directory
      *
      *  @param dir      Dir handle
-     *  return          0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure
      */
     virtual int dir_close(fs_dir_t dir);
 

hal/can_helper.h

@@ -25,6 +25,12 @@
 extern "C" {
 #endif
 
+/**
+ *
+ * \enum    CANFormat
+ *
+ * \brief   Values that represent CAN Format
+**/
 enum CANFormat {
     CANStandard = 0,
     CANExtended = 1,
@@ -32,18 +38,31 @@ enum CANFormat {
 };
 typedef enum CANFormat CANFormat;
 
+/**
+ *
+ * \enum    CANType
+ *
+ * \brief   Values that represent CAN Type
+**/
 enum CANType {
     CANData   = 0,
     CANRemote = 1
 };
 typedef enum CANType CANType;
 
+/**
+ *
+ * \struct  CAN_Message
+ *
+ * \brief   Holder for single CAN message.
+ *
+**/
 struct CAN_Message {
     unsigned int   id;                 // 29 bit identifier
     unsigned char  data[8];            // Data field
     unsigned char  len;                // Length of data field in bytes
-    CANFormat      format;             // 0 - STANDARD, 1- EXTENDED IDENTIFIER
-    CANType        type;               // 0 - DATA FRAME, 1 - REMOTE FRAME
+    CANFormat      format;             // Format ::CANFormat
+    CANType        type;               // Type ::CANType
 };
 typedef struct CAN_Message CAN_Message;
 

platform/DirHandle.h

@@ -54,7 +54,7 @@ public:
 
     /** Close a directory
      *
-     *  return          0 on success, negative error code on failure
+     *  @return          0 on success, negative error code on failure
      */
     virtual int close() = 0;
 

platform/FileHandle.h

@@ -170,7 +170,10 @@ public:
      *  Definition depends upon the subclass implementing FileHandle.
      *  The default is blocking.
      *
-     *  @param blocking true for blocking mode, false for non-blocking mode.
+     *  @param blocking     true for blocking mode, false for non-blocking mode.
+     *
+     *  @return             0 on success
+     *  @return             Negative error code on failure
      */
     virtual int set_blocking(bool blocking)
     {
@@ -183,10 +186,9 @@ public:
      * Call is non-blocking - returns instantaneous state of events.
      * Whenever an event occurs, the derived class should call the sigio() callback).
      *
-     * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc.
+     * @param events        bitmask of poll events we're interested in - POLLIN/POLLOUT etc.
      *
-     * @returns
-     *   bitmask of poll events that have occurred.
+     * @returns             bitmask of poll events that have occurred.
      */
     virtual short poll(short events) const
     {
@@ -194,20 +196,22 @@ public:
         return POLLIN | POLLOUT;
     }
 
-    /** Returns true if the FileHandle is writable.
-     *  Definition depends upon the subclass implementing FileHandle.
+    /** Definition depends upon the subclass implementing FileHandle.
      *  For example, if the FileHandle is of type Stream, writable() could return
      *  true when there is ample buffer space available for write() calls.
+     *
+     * @returns             true if the FileHandle is writable.
      */
     bool writable() const
     {
         return poll(POLLOUT) & POLLOUT;
     }
 
-    /** Returns true if the FileHandle is readable.
-     *  Definition depends upon the subclass implementing FileHandle.
+    /** Definition depends upon the subclass implementing FileHandle.
      *  For example, if the FileHandle is of type Stream, readable() could return
      *  true when there is something available to read.
+     *
+     *  @returns            true when there is something available to read.
      */
     bool readable() const
     {
@@ -239,11 +243,13 @@ public:
 
 /** Not a member function
  *  This call is equivalent to posix fdopen().
- *  Returns a pointer to std::FILE.
  *  It associates a Stream to an already opened file descriptor (FileHandle)
  *
- *  @param fh a pointer to an opened file descriptor
- *  @param mode operation upon the file descriptor, e.g., 'wb+'*/
+ *  @param fh       a pointer to an opened file descriptor
+ *  @param mode     operation upon the file descriptor, e.g., 'wb+'
+ *
+ *  @returns        a pointer to std::FILE
+*/
 
 std::FILE *fdopen(FileHandle *fh, const char *mode);
 

platform/mbed_error.h

@@ -19,7 +19,12 @@
 #ifndef MBED_ERROR_H
 #define MBED_ERROR_H
 
+
+
 /** To generate a fatal compile-time error, you can use the pre-processor #error directive.
+ *
+ * @param format    C string that contains data stream to be printed.
+ *                  Code snippets below show valid format.
  *
  * @code
  * #error "That shouldn't have happened!"
@@ -54,12 +59,13 @@
  *     error("expected x to be less than 5, but got %d", x);
  * }
  * @endcode
+ *
+ *
  */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
-
 void error(const char* format, ...);
 
 #ifdef __cplusplus

platform/mbed_interface.h

@@ -113,9 +113,17 @@ void mbed_mac_address(char *mac);
 void mbed_die(void);
 
 /** Print out an error message.  This is typically called when
- * hanlding a crash.
+ * handling a crash.
  *
  * @note Synchronization level: Interrupt safe
+ *
+ * @param format    C string that contains data stream to be printed.
+ *                  Code snippets below show valid format.
+ *
+ * @code
+ * mbed_error_printf("Failed: %s, file: %s, line %d \n", expr, file, line);
+ * @endcode
+ *
  */
 void mbed_error_printf(const char* format, ...);
 
@@ -123,6 +131,10 @@ void mbed_error_printf(const char* format, ...);
  * but uses a va_list.
  *
  * @note Synchronization level: Interrupt safe
+ *
+ * @param format    C string that contains data stream to be printed.
+ * @param arg       Variable arguments list
+ *
  */
 void mbed_error_vfprintf(const char * format, va_list arg);
 

platform/mbed_mem_trace.h

@@ -110,12 +110,12 @@ void mbed_mem_trace_free(void *ptr, void *caller);
  * easily parsable by an external tool. For each memory operation, the callback
  * outputs a line that begins with "#<op>:<0xresult>;<0xcaller>-":
  *
- * - 'op' identifies the memory operation ('m' for 'malloc', 'r' for 'realloc',
- *   'c' for 'calloc' and 'f' for 'free').
- * - 'result' (base 16) is the result of the memor operation. This is always NULL
- *   for 'free', since 'free' doesn't return anything.
- * - 'caller' (base 16) is the caller of the memory operation. Note that the value
- *   of 'caller' might be unreliable.
+ * @param op        identifies the memory operation ('m' for 'malloc', 'r' for 'realloc',
+ *                  'c' for 'calloc' and 'f' for 'free').
+ * @param res       (base 16) is the result of the memor operation. This is always NULL
+ *                  for 'free', since 'free' doesn't return anything.
+ * @param caller    (base 16) is the caller of the memory operation. Note that the value
+ *                  of 'caller' might be unreliable.
  *
  * The rest of the output depends on the operation being traced:
  *