Second time, Re-write doxygen tags in headers files to generate User API documentation
authorgreg
Mon, 19 Jan 2009 10:27:58 +0100
changeset 529 c171e11707c5
parent 528 0a30e161d63c
child 530 458418d7e10f
Second time, Re-write doxygen tags in headers files to generate User API documentation
doc/doxygen/Doxyfile
include/emcy.h
include/lifegrd.h
include/lss.h
include/nmtMaster.h
include/nmtSlave.h
include/objacces.h
include/pdo.h
include/sdo.h
include/states.h
include/sync.h
include/unix/canfestival.h
--- a/doc/doxygen/Doxyfile	Sat Jan 17 17:25:58 2009 +0100
+++ b/doc/doxygen/Doxyfile	Mon Jan 19 10:27:58 2009 +0100
@@ -31,7 +31,7 @@
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 3
+PROJECT_NUMBER         = 3.0
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
@@ -544,7 +544,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../../include
+INPUT                  = ../../include ../../src ../../drivers
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
--- a/include/emcy.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/emcy.h	Mon Jan 19 10:27:58 2009 +0100
@@ -30,6 +30,11 @@
 **
 */
  
+/** @defgroup emcyo Emergency Object
+ *  Emergency Object is used to communicate device and application failures.
+ *  @ingroup comobj
+ */
+					 
 #ifndef __emcy_h__
 #define __emcy_h__
 
--- a/include/lifegrd.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/lifegrd.h	Mon Jan 19 10:27:58 2009 +0100
@@ -20,6 +20,14 @@
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
 
+/** @defgroup heartbeato Heartbeat Object
+ *  The heartbeat mechanism for a device is established through cyclically transmitting a message by a
+ *	heartbeat producer. One or more devices in the network are aware of this heartbeat message. If the
+ *	heartbeat cycle fails for the heartbeat producer the local application on the heartbeat consumer will be
+ *	informed about that event.
+ *  @ingroup comobj
+ */
+					 
 #ifndef __lifegrd_h__
 #define __lifegrd_h__
 
@@ -39,6 +47,7 @@
  *************************************************************************/
 
 /** 
+ * @ingroup statemachine
  * @brief To read the state of a node
  * This can be used by the master after having sent a life guard request,
  * of by any node if it is waiting for heartbeat.
--- a/include/lss.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/lss.h	Mon Jan 19 10:27:58 2009 +0100
@@ -20,7 +20,14 @@
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
 
-/** @defgroup lss Layer setting Object
+/** @defgroup lss Layer Setting Services Object
+ * @brief LSS offers the possibility to inquire and change the settings of certain parameters of the local layers on
+ * a CANopen module with LSS Slave capabilities by a CANopen module with LSS Master capabilities via the
+ * CAN Network.
+ * The following parameters can be inquired and/or changed by the use of LSS:
+ *               - Node-ID of the CANopen Slave
+ *               - Bit timing parameters of the physical layer (baud rate)
+ *               - LSS address (/2/ Identity Object, Index 1018H)
  *  @ingroup comobj
  */
 					 
@@ -198,26 +205,39 @@
  */
 //UNS8 configNetworkNode(CO_Data* d, UNS8 command, void *dat1, void* dat2);
 
-/** Used by the Master application to send a LSS command, WITH response, to the slave. 
- * The function Callback, which must be defined in the user code, is called at the
+/** 
+ * @ingroup lss
+ * @brief Used by the Master application to send a LSS command, WITH response, to the slave. 
+ * @param *d Pointer on a CAN object data structure
+ * @param command
+ * @param *dat1
+ * @param *dat2
+ * @param Callback The function Callback, which must be defined in the user code, is called at the
  * end of the exchange (on succes or abort) and can be NULL.
+ * @return sendLSS(d,command,dat1,dat2)
  * The LSS_MSG_TIMER timer is started to control the timeout
- * return sendLSS(d,command,dat1,dat2)
  */
 UNS8 configNetworkNode (CO_Data* d, UNS8 command, void *dat1, void* dat2, LSSCallback_t Callback);
 
-/** Use this function after a configNetworkNode or configNetworkNodeCallBack to get the result.
-  Returns : LSS_RESET				// Transmission not started. Init state.
-			LSS_FINISHED			// data are available                           
-			LSS_ABORTED_INTERNAL	// Aborted but not because of an abort message. 
-			LSS_TRANS_IN_PROGRESS	// Data not yet available
-
-  * command: the LSS command (unused).
-  * example:
-  * UNS32 dat1;
-  * UNS8 dat2;
-  res=configNetworkNodeCallBack(&_Data,LSS_INQ_NODE_ID,0,0,NULL); // inquire the nodeID
-  while (getConfigResultNetworkNode (&_Data, LSS_INQ_NODE_ID, &dat1, &dat2) != LSS_TRANS_IN_PROGRESS);
+/**
+ * @ingroup lss 
+ * @brief Use this function after a configNetworkNode or configNetworkNodeCallBack to get the result.
+ * @param *d Pointer on a CAN object data structure
+ * @param command The LSS command (unused).
+ * @param *dat1
+ * @param *dat2
+ * @return : 
+ *          - LSS_RESET				// Transmission not started. Init state.
+ *          - LSS_FINISHED			// data are available                           
+ *          - LSS_ABORTED_INTERNAL	// Aborted but not because of an abort message. 
+ *          - LSS_TRANS_IN_PROGRESS	// Data not yet available
+ * @code
+ * example:
+ * UNS32 dat1;
+ * UNS8 dat2;
+ * res=configNetworkNodeCallBack(&_Data,LSS_INQ_NODE_ID,0,0,NULL); // inquire the nodeID
+ * while (getConfigResultNetworkNode (&_Data, LSS_INQ_NODE_ID, &dat1, &dat2) != LSS_TRANS_IN_PROGRESS);
+ * @endcode
 */
 UNS8 getConfigResultNetworkNode (CO_Data* d, UNS8 command, UNS32* dat1, UNS8* dat2);
 
--- a/include/nmtMaster.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/nmtMaster.h	Mon Jan 19 10:27:58 2009 +0100
@@ -24,6 +24,7 @@
  *  @ingroup userapi
  */
 /** @defgroup nmtmaster NMT Master
+ *  @brief NMT master provides mechanisms that control and monitor the state of nodes and their behavior in the network.
  *  @ingroup networkmanagement
  */
  
@@ -48,7 +49,7 @@
  *  - initialisation  ---> pre-operational (Automatic transition)
  *  - pre-operational <--> operational
  *  - pre-operational <--> stopped
- *  - pre-operational, operational, stopped -> initialisation
+ *  - pre-operational, operational, stopped -> initialisation\n
  * @param *d Pointer on a CAN object data structure
  * @param Node_ID Id of the slave node
  * @param cs State changement
--- a/include/nmtSlave.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/nmtSlave.h	Mon Jan 19 10:27:58 2009 +0100
@@ -21,6 +21,7 @@
 */
 
 /** @defgroup nmtslave NMT Slave
+ *  @brief The NMT Slave methods are called automatically when a NMT message from Master are received. 
  *  @ingroup networkmanagement
  */
  
@@ -31,7 +32,6 @@
 #include "data.h"
 
 /** 
- * @ingroup nmtslave
  * @brief Threat the reception of a NMT message from the master
  * bus_id is hardware dependant
  * @param *d Pointer on the CAN data structure
@@ -43,7 +43,6 @@
 void proceedNMTstateChange (CO_Data* d, Message * m);
 
 /** 
- * @ingroup nmtslave
  * @brief Transmit the boot-Up frame when the slave is moving from initialization
  * state to pre_operational state.
  * bus_id is hardware dependant
--- a/include/objacces.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/objacces.h	Mon Jan 19 10:27:58 2009 +0100
@@ -32,6 +32,7 @@
  */
 
 /** @defgroup od Object Dictionary Management
+ *  @brief The Object Dictionary is the heart of each CANopen device containing all communication and application objects.
  *  @ingroup userapi
  */
  
--- a/include/pdo.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/pdo.h	Mon Jan 19 10:27:58 2009 +0100
@@ -65,8 +65,7 @@
 #define TRANS_EVENT_SPECIFIC  254  /* Transmission on event */
 #define TRANS_EVENT_PROFILE   255  /* Transmission on event */
 
-/**
- * @ingroup pdo 
+/** 
  * @brief Copy all the data to transmit in process_var
  * Prepare the PDO defined at index to be sent
  * *pwCobId : returns the value of the cobid. (subindex 1)
@@ -97,8 +96,7 @@
  */
 UNS8 proceedPDO (CO_Data* d, Message *m);
 
-/**
- * @ingroup pdo 
+/** 
  * @brief Used by the application to signal changes in process data
  * that could be mapped to some TPDO.
  * This do not necessarily imply PDO emission.
@@ -118,14 +116,12 @@
 UNS8 _sendPDOevent(CO_Data* d, UNS8 isSyncEvent);
 
 /** 
- * @ingroup pdo
  * @brief Initialize PDO feature 
  * @param *d Pointer on a CAN object data structure
  */
 void PDOInit(CO_Data* d);
 
 /** 
- * @ingroup pdo
  * @brief Stop PDO feature 
  * @param *d Pointer on a CAN object data structure
  */
--- a/include/sdo.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/sdo.h	Mon Jan 19 10:27:58 2009 +0100
@@ -324,7 +324,9 @@
  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
  * @param *data Pointer on data
  * @param Callback Callback function
- * @param endianize
+ * @param endianize When not 0, data is endianized into network byte order
+ *                  when 0, data is not endianized and copied in machine native
+ *                  endianness
  * @return 0xFF if error, else return 0
  */
 UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,
@@ -389,12 +391,13 @@
  *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
  *           - SDO_UPLOAD_IN_PROGRESS   // Data not yet available
  *           - SDO_DOWNLOAD_IN_PROGRESS // Should not arrive !
- *
+ * @code
  * example :
  * UNS32 data;
  * UNS8 size;
  * readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5
  * while (getReadResultNetworkDict (0, 0x05, &data, &size) != SDO_UPLOAD_IN_PROGRESS);
+ * @endcode
 */
 UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS8 *size, UNS32 * abortCode);
 
@@ -412,12 +415,14 @@
  *           - SDO_DOWNLOAD_IN_PROGRESS // Data not yet available
  *           - SDO_UPLOAD_IN_PROGRESS   // Should not arrive !
  * 
+ * @code
  * example :
  * UNS32 data = 0x50;
  * UNS8 size;
  * UNS32 abortCode;
  * writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5
  * while (getWriteResultNetworkDict (0, 0x05, &abortCode) != SDO_DOWNLOAD_IN_PROGRESS);
+ * @endcode
 */
 UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);
 
--- a/include/states.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/states.h	Mon Jan 19 10:27:58 2009 +0100
@@ -62,7 +62,7 @@
 
 /** 
  * @brief Function that user app can overload
- * 
+ * @ingroup statemachine
  */
 typedef void (*initialisation_t)(CO_Data*);
 typedef void (*preOperational_t)(CO_Data*);
--- a/include/sync.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/sync.h	Mon Jan 19 10:27:58 2009 +0100
@@ -22,7 +22,7 @@
 
 /** @defgroup synco Synchronisation Object
  *  SYNC object is a CANopen message forcing the receiving nodes to sample the inputs mapped into synchronous TPDOS.
- *  Receiving this message causse the node to set the outputs to values received in the previous synchronous RPDO.
+ *  Receiving this message cause the node to set the outputs to values received in the previous synchronous RPDO.
  *  @ingroup comobj
  */
 					 
@@ -40,7 +40,6 @@
 void _post_TPDO(CO_Data* d);
 
 /** 
- * @ingroup synco
  * @brief Transmit a SYNC message and trigger sync TPDOs
  * @param *d Pointer on a CAN object data structure
  * @return
@@ -48,7 +47,6 @@
 UNS8 sendSYNC (CO_Data* d);
 
 /** 
- * @ingroup synco
  * @brief Transmit a SYNC message on CAN bus
  * @param *d Pointer on a CAN object data structure
  * @return
--- a/include/unix/canfestival.h	Sat Jan 17 17:25:58 2009 +0100
+++ b/include/unix/canfestival.h	Mon Jan 19 10:27:58 2009 +0100
@@ -44,7 +44,6 @@
 LIB_HANDLE LoadCanDriver(const char* driver_name);
 
 /**
- * @ingroup can
  * @brief Send a CAN message
  * @param port CanFestival file descriptor
  * @param *m The message to send
@@ -63,7 +62,7 @@
 
 /**
  * @ingroup can
- * @brief Stop the timer task
+ * @brief Close a CANopen device
  * @param *d Pointer on the CAN object data structure
  * @return 0 if succes
  */
@@ -71,7 +70,7 @@
 
 /**
  * @ingroup can
- * @brief Stop the timer task
+ * @brief Change the CANopen device baudrate 
  * @param port CanFestival file descriptor 
  * @param *baud The new baudrate to assign
  * @return 0 if succes