From: greg Date: Mon, 19 Jan 2009 09:27:57 +0000 (+0000) Subject: Second time, Re-write doxygen tags in headers files to generate User API documentation X-Git-Url: https://rtime.felk.cvut.cz/gitweb/CanFestival-3.git/commitdiff_plain/4bddbd28701c1e8b50513d2bdf41113c459cbcd1 Second time, Re-write doxygen tags in headers files to generate User API documentation --- diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index fc52ffd..51ef3fe 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -31,7 +31,7 @@ PROJECT_NAME = CanFestival # 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 @@ WARN_LOGFILE = # 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 diff --git a/include/emcy.h b/include/emcy.h index 7c924db..d3a19eb 100644 --- a/include/emcy.h +++ b/include/emcy.h @@ -30,6 +30,11 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ** */ +/** @defgroup emcyo Emergency Object + * Emergency Object is used to communicate device and application failures. + * @ingroup comobj + */ + #ifndef __emcy_h__ #define __emcy_h__ diff --git a/include/lifegrd.h b/include/lifegrd.h index 79f9b0c..f650199 100644 --- a/include/lifegrd.h +++ b/include/lifegrd.h @@ -20,6 +20,14 @@ License along with this library; if not, write to the Free Software 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 @@ void _post_SlaveBootup(CO_Data* d, UNS8 SlaveID); *************************************************************************/ /** + * @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. diff --git a/include/lss.h b/include/lss.h index c4e2de5..06a77fc 100644 --- a/include/lss.h +++ b/include/lss.h @@ -20,7 +20,14 @@ License along with this library; if not, write to the Free Software 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 proceedLSS_Slave (CO_Data* d, Message* m ); */ //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); diff --git a/include/nmtMaster.h b/include/nmtMaster.h index 4a6865c..f7bda6d 100644 --- a/include/nmtMaster.h +++ b/include/nmtMaster.h @@ -24,6 +24,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * @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 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * - 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 diff --git a/include/nmtSlave.h b/include/nmtSlave.h index 3b30bfe..ec667a1 100644 --- a/include/nmtSlave.h +++ b/include/nmtSlave.h @@ -21,6 +21,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ /** @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 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA #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 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 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 diff --git a/include/objacces.h b/include/objacces.h index a40734b..e819f29 100644 --- a/include/objacces.h +++ b/include/objacces.h @@ -32,6 +32,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ /** @defgroup od Object Dictionary Management + * @brief The Object Dictionary is the heart of each CANopen device containing all communication and application objects. * @ingroup userapi */ diff --git a/include/pdo.h b/include/pdo.h index a3fa2a9..03af28b 100644 --- a/include/pdo.h +++ b/include/pdo.h @@ -65,8 +65,7 @@ struct struct_s_PDO_status { #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 sendPDOrequest( CO_Data* d, UNS16 RPDOIndex ); */ 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 _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 */ diff --git a/include/sdo.h b/include/sdo.h index ea592a2..96245c7 100644 --- a/include/sdo.h +++ b/include/sdo.h @@ -324,7 +324,9 @@ UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index, * @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 @@ UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIn * - 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 @@ UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS8 *size, * - 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); diff --git a/include/states.h b/include/states.h index ea2879e..4709e09 100644 --- a/include/states.h +++ b/include/states.h @@ -62,7 +62,7 @@ typedef struct /** * @brief Function that user app can overload - * + * @ingroup statemachine */ typedef void (*initialisation_t)(CO_Data*); typedef void (*preOperational_t)(CO_Data*); diff --git a/include/sync.h b/include/sync.h index bb0e0c8..241dfbb 100644 --- a/include/sync.h +++ b/include/sync.h @@ -22,7 +22,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA /** @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 @@ typedef void (*post_TPDO_t)(CO_Data*); 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 @@ void _post_TPDO(CO_Data* d); 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 diff --git a/include/unix/canfestival.h b/include/unix/canfestival.h index c403b55..7eb1490 100644 --- a/include/unix/canfestival.h +++ b/include/unix/canfestival.h @@ -44,7 +44,6 @@ UNS8 UnLoadCanDriver(LIB_HANDLE handle); 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 @@ CAN_PORT canOpen(s_BOARD *board, CO_Data * d); /** * @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 @@ int canClose(CO_Data * d); /** * @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