Fix nasa#559, update comments to fix doxygen warnings (WIP)

cmake/cfe-common.doxyfile.in

@@ -227,12 +227,12 @@ TAGFILES               =
 GENERATE_TAGFILE       = 
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
+#PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool   
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = NO
-MSCGEN_PATH            = 
+#MSCGEN_PATH            = 
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES
 CLASS_GRAPH            = NO
@@ -273,4 +273,3 @@ SEARCHENGINE           = NO
 @INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_evs_tlm_mnem_map
 @INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_sb_cmd_mnem_map
 @INCLUDE = @MISSION_SOURCE_DIR@/cfe/docs/src/mnem_maps/cfe_sb_tlm_mnem_map
-

cmake/osal-common.doxyfile.in

@@ -203,12 +203,12 @@ TAGFILES               =
 GENERATE_TAGFILE       = 
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
+#PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool   
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = NO
-MSCGEN_PATH            = 
+#MSCGEN_PATH            = 
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES
 CLASS_GRAPH            = NO
@@ -240,4 +240,3 @@ SEARCHENGINE           = NO
 # OSAL mnemonic mappings
 #---------------------------------------------------------------------------
 #@INCLUDE = 
-

fsw/cfe-core/src/es/cfe_es_cds.h

@@ -58,6 +58,8 @@
 #define CFE_ES_CDS_MUT_REG_VALUE       0             /**< \brief Initial Value of CDS Registry Access Mutex */
 
 #define CFE_ES_CDS_NOT_FOUND          (uint32)(0xffffffff)
+/** \} */
+
 /*
 ** Type Definitions
 */
@@ -121,9 +123,8 @@ int32 CFE_ES_UpdateCDSRegistry(void);
 ** \par Assumptions, External Events, and Notes:
 **          None
 **
-** \param[in]  AppIdPtr Pointer to value that will hold AppID on return.
+** \param[in, out]  AppIdPtr Pointer to value that will hold AppID on return. *AppIdPtr is the AppID as obtained from #CFE_ES_GetAppID.
 ** 
-** \param[out] *AppIdPtr The AppID as obtained from #CFE_ES_GetAppID
 **
 ** \retval #CFE_SUCCESS                     \copydoc CFE_SUCCESS
 ** \retval #CFE_ES_ERR_APPID                \copydoc CFE_ES_ERR_APPID
@@ -144,17 +145,15 @@ int32 CFE_ES_CDS_ValidateAppID(uint32 *AppIdPtr);
 ** \par Assumptions, External Events, and Notes:
 **        Note: AppName portion will be truncated to OS_MAX_API_NAME.
 **
-** \param[in]  FullCDSName pointer to character buffer of #CFE_ES_CDS_MAX_FULL_NAME_LEN size
-**                         that will be filled with the processor specific CDS Name.
+** \param[in, out]  FullCDSName pointer to character buffer of #CFE_ES_CDS_MAX_FULL_NAME_LEN size
+**                         that will be filled with the processor specific CDS Name. *FullCDSName is the processor specific CDS Name of the form "AppName.CDSName".
 ** 
 ** \param[in]  CDSName pointer to character string containing the Application's local name for
 **                     the CDS.
 **
 ** \param[in]  ThisAppId the Application ID of the Application making the call. 
 **
-** \param[out] *FullCDSName processor specific CDS Name of the form "AppName.CDSName".
 **
-** \retval None                     
 ******************************************************************************/
 void CFE_ES_FormCDSName(char *FullCDSName, const char *CDSName, uint32 ThisAppId);
 
@@ -173,7 +172,7 @@ void CFE_ES_FormCDSName(char *FullCDSName, const char *CDSName, uint32 ThisAppId
 **                       CDS Name (of the format "AppName.CDSName").
 ** 
 ** \retval #CFE_ES_CDS_NOT_FOUND or the Index into Registry for Table with specified name
-**                     
+**
 ******************************************************************************/
 int32  CFE_ES_FindCDSInRegistry(const char *CDSName);
 

fsw/cfe-core/src/inc/cfe_es.h

@@ -670,9 +670,8 @@ int32 CFE_ES_GetResetType(uint32 *ResetSubtypePtr);
 ** \par Assumptions, External Events, and Notes:
 **        NOTE: \b All tasks associated with the Application would return the same Application ID.
 **
-** \param[in]   AppIdPtr       Pointer to variable that is to receive the Application's ID.
+** \param[in]   AppIdPtr       Pointer to variable that is to receive the Application's ID. *AppIdPtr is the application ID of the calling Application.
 **
-** \param[out]  *AppIdPtr      Application ID of the calling Application.
 **
 ** \return Execution status, see \ref CFEReturnCodes
 ** \retval #CFE_SUCCESS       \copybrief CFE_SUCCESS
@@ -695,11 +694,10 @@ int32 CFE_ES_GetAppID(uint32 *AppIdPtr);
 ** \par Assumptions, External Events, and Notes:
 **        None
 **
-** \param[in]   AppIdPtr       Pointer to variable that is to receive the Application's ID.
+** \param[in]   AppIdPtr       Pointer to variable that is to receive the Application's ID. *AppIdPtr is the application ID of the calling Application.
 **
 ** \param[in]   AppName        Pointer to null terminated character string containing an Application name.
 **
-** \param[out]  *AppIdPtr      Application ID of the calling Application.
 **
 ** \return Execution status, see \ref CFEReturnCodes
 ** \retval #CFE_SUCCESS         \copybrief CFE_SUCCESS

fsw/cfe-core/src/inc/cfe_sb_msg.h

@@ -54,7 +54,7 @@
 **  \cfecmdmnemonic \SB_NOOP
 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t
 **
 **  \par Command Verification
 **       Successful execution of this command may be verified with the
@@ -88,7 +88,7 @@
 **  \cfecmdmnemonic \SB_RESETCTRS
 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t
 **
 **  \par Command Verification
 **       Successful execution of this command may be verified with the
@@ -125,7 +125,7 @@
 **  \cfecmdmnemonic \SB_DUMPSTATS
 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t
 **
 **  \par Command Verification
 **       Successful execution of this command may be verified with the
@@ -379,7 +379,7 @@
 **  \cfecmdmnemonic \SB_ENASUBRPTG
 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t
 **
 **  \par Command Verification
 **       Successful execution of this command will result in the sending
@@ -411,7 +411,7 @@
 **  \cfecmdmnemonic \SB_DISSUBRPTG
 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t
 **
 **  \par Command Verification
 **       Successful execution of this command will result in the suppression
@@ -443,7 +443,7 @@
 **  \cfecmdmnemonic \SB_SENDPREVSUBS
 **
 **  \par Command Structure
-**       #CFE_SB_CmdHdr_t
+**       cfe_sb.h::CFE_SB_CmdHdr_t
 **
 **  \par Command Verification
 **       Successful execution of this command will result in a series
@@ -494,7 +494,7 @@ typedef struct{
 } CFE_SB_WriteFileInfoCmd_Payload_t;
 
 typedef struct{
-    CFE_SB_CmdHdr_t                     Hdr;/**< \brief cFE Software Bus Command Message Header #CFE_SB_CmdHdr_t */
+    CFE_SB_CmdHdr_t                     Hdr;/**< \brief cFE Software Bus Command Message Header cfe_sb.h::CFE_SB_CmdHdr_t */
     CFE_SB_WriteFileInfoCmd_Payload_t   Payload;
 }CFE_SB_WriteFileInfoCmd_t;
 
@@ -521,7 +521,7 @@ typedef struct {
 } CFE_SB_RouteCmd_Payload_t;
 
 typedef struct{
-    CFE_SB_CmdHdr_t             Hdr;/**< \brief cFE Software Bus Command Message Header #CFE_SB_CmdHdr_t */
+    CFE_SB_CmdHdr_t             Hdr;/**< \brief cFE Software Bus Command Message Header cfe_sb.h::CFE_SB_CmdHdr_t */
     CFE_SB_RouteCmd_Payload_t  Payload;
 } CFE_SB_RouteCmd_t;
 

fsw/cfe-core/src/inc/cfe_tbl_events.h

@@ -66,6 +66,8 @@
 **  Task completes its Initialization.
 **/
 #define CFE_TBL_INIT_INF_EID                    1  
+/** \} */
+
 
 /** \name Command Response Informational Event Message IDs */
 /** \{ */
@@ -841,6 +843,7 @@
 #define CFE_TBL_FAIL_NOTIFY_SEND_ERR_EID       89
 /** \} */
 
+
 /** \name API Informational Event Message IDs */
 /** \{ */
 
@@ -895,7 +898,6 @@
 /** \} */
 
 
-
 /** \name API Error Event Message IDs */
 /** \{ */
 /** \brief <tt> '\%s Failed to Register '\%s', Status=0x\%08X' </tt>
@@ -1055,7 +1057,6 @@
 /** \} */
 
 
-
 #endif /* _cfe_tbl_events_ */
 
 /************************/

fsw/cfe-core/src/inc/private/cfe_private.h

@@ -52,7 +52,7 @@
 ** \par Assumptions, External Events, and Notes:
 **          None
 **
-** \retval None
+** 
 ******************************************************************************/
 extern void CFE_TIME_TaskMain(void);
 
@@ -66,7 +66,7 @@ extern void CFE_TIME_TaskMain(void);
 ** \par Assumptions, External Events, and Notes:
 **          None
 **
-** \retval None
+** 
 ******************************************************************************/
 extern void CFE_SB_TaskMain(void);
 
@@ -80,7 +80,7 @@ extern void CFE_SB_TaskMain(void);
 ** \par Assumptions, External Events, and Notes:
 **          None
 **
-** \retval None
+** 
 ******************************************************************************/
 extern void CFE_EVS_TaskMain(void);
 
@@ -94,7 +94,7 @@ extern void CFE_EVS_TaskMain(void);
 ** \par Assumptions, External Events, and Notes:
 **          None
 **
-** \retval None
+** 
 ******************************************************************************/
 extern void CFE_ES_TaskMain(void);
 
@@ -110,7 +110,7 @@ extern void CFE_ES_TaskMain(void);
 ** \par Assumptions, External Events, and Notes:
 **          None
 **
-** \retval None
+** 
 ******************************************************************************/
 extern void CFE_TBL_TaskMain(void);
 
@@ -290,7 +290,7 @@ extern int32 CFE_TIME_CleanUpApp(uint32 AppId);
 **        -# This function assumes input parameters are error free and have met size/value restrictions.
 **        -# The calling function is responsible for issuing any event messages associated with errors.
 **
-** \param[in]   HandlePtr   Pointer Application's variable that will contain the CDS Memory Block Handle.
+** \param[in, out]   HandlePtr   Pointer Application's variable that will contain the CDS Memory Block Handle. *HandlePtr is the handle of the CDS block that can be used in #CFE_ES_CopyToCDS and #CFE_ES_RestoreFromCDS.
 **
 ** \param[in]   BlockSize   The number of bytes needed in the CDS.
 **
@@ -299,7 +299,6 @@ extern int32 CFE_TIME_CleanUpApp(uint32 AppId);
 **
 ** \param[in]   CriticalTbl   Indicates whether the CDS is to be used as a Critical Table or not
 **
-** \param[out]  *HandlePtr  The handle of the CDS block that can be used in #CFE_ES_CopyToCDS and #CFE_ES_RestoreFromCDS.
 **
 ** \return See return codes for #CFE_ES_RegisterCDS
 **

fsw/cfe-core/src/sb/cfe_sb_priv.h

@@ -417,18 +417,16 @@ int32 CFE_SB_RemoveDest(CFE_SB_RouteEntry_t *RouteEntry, CFE_SB_DestinationD_t *
 **
 ** \par Assumptions, External Events, and Notes:
 **          - For statically defined messages, a function call will not work.  The 
-**            macros #CFE_SB_CMD_HDR_SIZE and #CFE_SB_TLM_HDR_SIZE are available for use 
+**            macros cfe_sb.h::CFE_SB_CMD_HDR_SIZE and cfe_sb.h::CFE_SB_TLM_HDR_SIZE are available for use 
 **            in static message buffer sizing or structure definitions.  
 **
 ** \param[in]  *MsgPtr The message ID to calculate header size for.  The size of the message 
 **                     header may depend on the MsgId in some implementations.  For example, 
 **                     if SB messages are implemented as CCSDS packets, the size of the header 
 **                     is different for command vs. telemetry packets.
 **
-** \returns
-** \retstmt The number of bytes in the software bus message header for 
-**          messages with the given \c MsgId. endstmt
-** \endreturns
+** \returns The number of bytes in the software bus message header for 
+**          messages with the given \c MsgId.
 **
 ** \sa #CFE_SB_GetUserData, #CFE_SB_GetMsgId, #CFE_SB_GetUserDataLength, #CFE_SB_GetTotalMsgLength,
 **     #CFE_SB_GetMsgTime, #CFE_SB_GetCmdCode, #CFE_SB_GetChecksum