Merge pull request #1560 from skliper/fix1494-tbltime_doc_cleanup

Fix #1494, Documentation cleanup in TBL/TIME

modules/core_api/fsw/inc/cfe_tbl.h

@@ -313,13 +313,10 @@ CFE_Status_t CFE_TBL_Load(CFE_TBL_Handle_t TblHandle, CFE_TBL_SrcEnum_t SrcType,
 ** \brief Update contents of a specified table, if an update is pending
 **
 ** \par Description
-**        An application is \b required to perform a periodic check for an update
-**        for all the tables that it creates.  Typically, the application that
-**        created the table would call this function at the start or conclusion
-**        of any routine processing cycle or at regular intervals.  To determine
-**        whether an update is pending prior to making this call, the Application
-**        can use the #CFE_TBL_GetStatus API first.  If a table update is pending,
-**        it will take place during this function call.
+**        Typically, apps should just call #CFE_TBL_Manage as part
+**        of routine processing which will perform validation, update, or dump
+**        if pending. This API is provided for the case where just an
+**        update should be performed.
 **
 ** \par Assumptions, External Events, and Notes:
 **          None
@@ -344,13 +341,10 @@ CFE_Status_t CFE_TBL_Update(CFE_TBL_Handle_t TblHandle);
 ** \brief Perform steps to validate the contents of a table image.
 **
 ** \par Description
-**        An application is \b required to perform a periodic check for an update
-**        or a validation request for all the tables that it creates.  Typically,
-**        the application that created the table would call this function at the
-**        start or conclusion of any routine processing cycle.  To determine whether
-**        a validation request is pending prior to making this call, the Application
-**        can use the #CFE_TBL_GetStatus API first.  If a table validation is pending,
-**        the Application would call this function to perform the necessary actions.
+**        Typically, apps should just call #CFE_TBL_Manage as part
+**        of routine processing which will perform validation, update, or dump
+**        if pending. This API is provided for the case where just a
+**        validation should be performed.
 **
 ** \par Assumptions, External Events, and Notes:
 **          None
@@ -375,12 +369,10 @@ CFE_Status_t CFE_TBL_Validate(CFE_TBL_Handle_t TblHandle);
 ** \brief Perform standard operations to maintain a table.
 **
 ** \par Description
-**        An application is \b required to perform a periodic check for an update
-**        or a validation request for all the tables that it creates.  Typically,
+**        Applications should call this API periodically to process pending
+**        requests for update, validation, or dump to buffer.  Typically,
 **        the application that created the table would call this function at the
-**        start or conclusion of any routine processing cycle.  If a table update
-**        or validation request is pending, this function would perform either or
-**        both before returning.
+**        start or conclusion of any routine processing cycle.
 **
 ** \par Assumptions, External Events, and Notes:
 **          None
@@ -405,14 +397,13 @@ CFE_Status_t CFE_TBL_Manage(CFE_TBL_Handle_t TblHandle);
 ** \brief Copies the contents of a Dump Only Table to a shared buffer
 **
 ** \par Description
-**        Copies contents of a Dump Only table to a shared buffer so that it
-**        can be written to a file by the Table Services routine.  This function
-**        is called by the Application that owns the table in response to a #CFE_TBL_INFO_DUMP_PENDING
-**        status obtained via #CFE_TBL_GetStatus.
+**        Typically, apps should just call #CFE_TBL_Manage as part
+**        of routine processing which will perform validation, update, or dump
+**        if pending. This API is provided for the case where just a
+**        dump should be performed.
 **
 ** \par Assumptions, External Events, and Notes:
-**        -# If the table does not have a dump pending status, nothing will occur (no error, no dump)
-**        -# Applications may wish to use this function in lieu of #CFE_TBL_Manage for their Dump Only tables
+**        If the table does not have a dump pending status, nothing will occur (no error, no dump)
 **
 ** \param[in]  TblHandle      Handle of Table to be dumped.
 **
@@ -545,7 +536,7 @@ CFE_Status_t CFE_TBL_ReleaseAddress(CFE_TBL_Handle_t TblHandle);
 **        When a table has been created and initialized, it is available to
 **        any application that can identify it with its unique handle.  In
 **        order to view the data contained in the table, an application must
-**        call this function or #CFE_TBL_GetAddresses.
+**        call this function or #CFE_TBL_GetAddress.
 **
 ** \par Assumptions, External Events, and Notes:
 **        -# This call can be a blocking call when the table is not double buffered

modules/core_api/fsw/inc/cfe_time.h

@@ -67,12 +67,13 @@
 ** \brief Get the current spacecraft time
 **
 ** \par Description
-**        This routine returns the current spacecraft time.  The time returned
+**        This routine returns the current spacecraft time, which is the amount of
+**        time elapsed since the epoch as set in mission configuration.  The time returned
 **        is either TAI (no leap seconds) or UTC (including leap seconds).  This choice
 **        is made in the mission configuration file by defining either #CFE_MISSION_TIME_CFG_DEFAULT_TAI
 **        or #CFE_MISSION_TIME_CFG_DEFAULT_UTC as true at compile time.  To maintain re-usability
 **        across missions, most applications should be using this function
-**        (or #CFE_TIME_GetTime) rather than the specific routines for getting UTC/TAI directly.
+**        rather than the specific routines for getting UTC/TAI directly.
 **
 ** \par Assumptions, External Events, and Notes:
 **          None
@@ -215,10 +216,10 @@ uint32 CFE_TIME_GetMETsubsecs(void);
 ** \par Description
 **        This routine returns the current value of the spacecraft time correction
 **        factor.  This is the delta time between the MET and the TAI time.
-**        Applications cannot set or adjust the STCF; that can only be done
-**        through ground commands.  However, science applications may want to
-**        include the STCF in their data products to aid in time correlation
-**        during downstream science data processing.
+**        There is no API provided to set or adjust leap seconds or SCTF, those
+**        actions should be done by command only.  This API is provided for
+**        applications to be able to include STCF in their data products to
+**        aid in time correlation during downstream science data processing.
 **
 ** \par Assumptions, External Events, and Notes:
 **        Does not include leap seconds
@@ -237,11 +238,12 @@ CFE_TIME_SysTime_t CFE_TIME_GetSTCF(void);
 ** \par Description
 **        This routine returns the current value of the leap seconds counter.
 **        This is the delta seconds between international atomic time (TAI)
-**        and universal coordinated time (UTC).  Applications cannot set or
-**        adjust the leap seconds; that can only be done through ground commands.
-**        However, science applications may want to include the leap seconds
-**        counter in their data products to aid in time correlation during
-**        downstream science data processing.  Note that some mission operations
+**        and universal coordinated time (UTC).
+**        There is no API provided to set or adjust leap seconds or SCTF, those
+**        actions should be done by command only.  This API is provided for
+**        applications to be able to include leap seconds in their data products to
+**        aid in time correlation during downstream science data processing.
+**        Note that some mission operations
 **        teams do not maintain the leap seconds count, preferring to adjust the
 **        STCF instead.  Users of this function should check with their mission
 **        ops team to see how they are planning to handle leap seconds.
@@ -705,7 +707,8 @@ void CFE_TIME_Print(char *PrintBuffer, CFE_TIME_SysTime_t TimeToPrint);
 
 /*****************************************************************************/
 /**
-** \brief This function should be called from the system PSP layer once per second
+** \brief This function is called via a timer callback set up at initialization
+**        of the TIME service.
 **
 ** \par Description
 **        Drives the time processing logic from the system PSP layer.  This must be called

modules/tbl/fsw/src/cfe_tbl_task_cmds.c

@@ -1263,7 +1263,7 @@ int32 CFE_TBL_DumpRegistryCmd(const CFE_TBL_DumpRegistryCmd_t *data)
             /*
              * Before submitting the background request, use OS_stat() to check if the file exists already.
              *
-             * This is because TBL services issued a different event ID in some cases if
+             * This is needed because TBL services issues a different event ID in some cases if
              * it is overwriting a file vs. creating a new file.
              */
             StatePtr->FileExisted = (OS_stat(StatePtr->FileWrite.FileName, &FileStat) == OS_SUCCESS);

modules/tbl/fsw/src/cfe_tbl_task_cmds.h

@@ -124,7 +124,9 @@ extern void CFE_TBL_GetTblRegData(void);
 ** \brief Process Housekeeping Request Message
 **
 ** \par Description
-**        Constructs a Housekeeping Packet (#CFE_TBL_HousekeepingTlm_t) from task data and sends it out
+**        Constructs and sends a Housekeeping Packet (#CFE_TBL_HousekeepingTlm_t) from task data,
+**        sends the table registry packet if requested, and dumps any "dump-only" tables
+**        that are pending.
 **
 ** \par Assumptions, External Events, and Notes:
 **          The message pointed to by data has been identified as a Housekeeping Request Message

modules/tbl/fsw/src/cfe_tbl_verify.h

@@ -73,13 +73,6 @@
 #error CFE_PLATFORM_TBL_START_TASK_STACK_SIZE must be greater than or equal to 2048
 #endif
 
-/* the following check is removed because some compilers cannot handle the sizeof operator in a #if statement */
-/*
-#if sizeof(CFE_PLATFORM_TBL_DEFAULT_REG_DUMP_FILE) > OS_MAX_PATH_LEN
-    #error The length (including NULL terminator) of CFE_PLATFORM_TBL_DEFAULT_REG_DUMP_FILE cannot be greater than
-OS_MAX_PATH_LEN #endif
-*/
-
 /*
  * For configuration values that should be multiples of 4
  * as noted in the documentation, this confirms that they are.

modules/time/fsw/src/cfe_time_tone.c

@@ -711,9 +711,6 @@ void CFE_TIME_ToneVerify(CFE_TIME_SysTime_t Time1, CFE_TIME_SysTime_t Time2)
     static CFE_TIME_SysTime_t PrevTime1 = {0, 0};
     static CFE_TIME_SysTime_t PrevTime2 = {0, 0};
 
-    /*
-    ** It is possible to call this func with static time value...
-    */
     result = CFE_TIME_Compare(PrevTime1, Time1);
     if (result == CFE_TIME_EQUAL)
     {