Fix nasa#1355, improve documentation for resourceID patterns

Improve the doxygen documentation on the various helper functions
and common patterns dealing with Resource IDs.  Specifically, document
that the "IsMatch()" functions specifically accept NULL pointers to
allow use with initial validation (gatekeeper), but all other helper
functions assume a non-NULL pointer.

modules/es/fsw/src/cfe_es_cds.h

@@ -267,12 +267,24 @@ int32 CFE_ES_CDSHandle_ToIndex(CFE_ES_CDSHandle_t BlockID, uint32 *Idx);
 /**
  * @brief Get a registry record within the CDS, given a block ID/handle
  *
- * Retrieves a pointer to the registry record associated with a CDS block ID/handle
- * Returns NULL if the handle is outside the valid range
+ * This only returns a pointer to the table entry where the record
+ * should reside, but does _not_ actually check/validate the entry.
  *
- * @note This only does the lookup, it does not validate that the handle
- * actually matches the returned record.  The caller should lock the CDS and
- * confirm that the record is a match to the expected ID before using it.
+ * If the passed-in ID parameter is not within the acceptable range of ID
+ * values for CDS blocks, such that it could never be valid under
+ * any circumstances, then NULL is returned.  Otherwise, a pointer to the
+ * corresponding table entry is returned, indicating the location where
+ * that ID _should_ reside, if it is currently in use.
+ *
+ * @note This only returns where the ID should reside, not that it actually
+ * resides there.  If looking up an existing ID, then caller must additionally
+ * confirm that the returned record is a match to the expected ID before using
+ * or modifying the data within the returned record pointer.
+ *
+ * The CFE_ES_CDSBlockRecordIsMatch() function can be used to check/confirm
+ * if the returned table entry is a positive match for the given ID.
+ *
+ * @sa CFE_ES_CDSBlockRecordIsMatch()
  *
  * @param[in] BlockID the ID/handle of the CDS block to retrieve
  * @returns   Pointer to registry record, or NULL if ID/handle invalid.
@@ -287,6 +299,9 @@ CFE_ES_CDS_RegRec_t *CFE_ES_LocateCDSBlockRecordByID(CFE_ES_CDSHandle_t BlockID)
  * As this dereferences fields within the record, global data must be
  * locked prior to invoking this function.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   CDSBlockRecPtr   pointer to Pool table entry
  * @returns true if the entry is in use/configured, or false if it is free/empty
  */
@@ -300,6 +315,9 @@ static inline bool CFE_ES_CDSBlockRecordIsUsed(const CFE_ES_CDS_RegRec_t *CDSBlo
  *
  * This routine converts the table entry back to an abstract ID.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   CDSBlockRecPtr   pointer to Pool table entry
  * @returns BlockID of entry
  */
@@ -314,6 +332,9 @@ static inline CFE_ES_CDSHandle_t CFE_ES_CDSBlockRecordGetID(const CFE_ES_CDS_Reg
  * This sets the internal field(s) within this entry, and marks
  * it as being associated with the given Pool ID.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   CDSBlockRecPtr   pointer to Pool table entry
  * @param[in]   PendingId        the Pool ID of this entry
  */
@@ -328,6 +349,9 @@ static inline void CFE_ES_CDSBlockRecordSetUsed(CFE_ES_CDS_RegRec_t *CDSBlockRec
  * This clears the internal field(s) within this entry, and allows the
  * memory to be re-used in the future.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   CDSBlockRecPtr   pointer to Pool table entry
  */
 static inline void CFE_ES_CDSBlockRecordSetFree(CFE_ES_CDS_RegRec_t *CDSBlockRecPtr)
@@ -344,6 +368,16 @@ static inline void CFE_ES_CDSBlockRecordSetFree(CFE_ES_CDS_RegRec_t *CDSBlockRec
  * As this dereferences fields within the record, CDS access mutex must be
  * locked prior to invoking this function.
  *
+ * This function may be used in conjunction with CFE_ES_LocateCDSBlockRecordByID()
+ * to confirm that the located record is a positive match to the expected ID.
+ * As such, the record pointer is also permitted to be NULL, to alleviate the
+ * need for the caller to handle this possibility explicitly.
+ *
+ * Once a record pointer has been successfully validated using this routine,
+ * it may be safely passed to all other internal functions.
+ *
+ * @sa CFE_ES_LocateCDSBlockRecordByID
+ *
  * @param[in]   CDSBlockRecPtr   pointer to registry table entry
  * @param[in]   BlockID          expected block ID
  * @returns true if the entry matches the given block ID
@@ -365,6 +399,9 @@ static inline bool CFE_ES_CDSBlockRecordIsMatch(const CFE_ES_CDS_RegRec_t *CDSBl
  * which contains error checking information.  Therefore the usable data
  * size is less than the raw block size.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   CDSBlockRecPtr   pointer to registry table entry
  * @returns     Usable size of the CDS
  */

modules/es/fsw/src/cfe_es_mempool.h

@@ -100,8 +100,24 @@ int32 CFE_ES_MemPoolID_ToIndex(CFE_ES_MemHandle_t PoolID, uint32 *Idx);
 /**
  * @brief Locate the Pool table entry correlating with a given Pool ID.
  *
- * This only returns a pointer to the table entry and does _not_
- * otherwise check/validate the entry.
+ * This only returns a pointer to the table entry where the record
+ * should reside, but does _not_ actually check/validate the entry.
+ *
+ * If the passed-in ID parameter is not within the acceptable range of ID
+ * values for memory pools, such that it could never be valid under
+ * any circumstances, then NULL is returned.  Otherwise, a pointer to the
+ * corresponding table entry is returned, indicating the location where
+ * that ID _should_ reside, if it is currently in use.
+ *
+ * @note This only returns where the ID should reside, not that it actually
+ * resides there.  If looking up an existing ID, then caller must additionally
+ * confirm that the returned record is a match to the expected ID before using
+ * or modifying the data within the returned record pointer.
+ *
+ * The CFE_ES_MemPoolRecordIsMatch() function can be used to check/confirm
+ * if the returned table entry is a positive match for the given ID.
+ *
+ * @sa CFE_ES_MemPoolRecordIsMatch()
  *
  * @param[in]   PoolID   the Pool ID to locate
  * @return pointer to Pool Table entry for the given Pool ID
@@ -116,6 +132,9 @@ CFE_ES_MemPoolRecord_t *CFE_ES_LocateMemPoolRecordByID(CFE_ES_MemHandle_t PoolID
  * As this dereferences fields within the record, global data must be
  * locked prior to invoking this function.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   PoolRecPtr   pointer to Pool table entry
  * @returns true if the entry is in use/configured, or false if it is free/empty
  */
@@ -129,6 +148,9 @@ static inline bool CFE_ES_MemPoolRecordIsUsed(const CFE_ES_MemPoolRecord_t *Pool
  *
  * This routine converts the table entry back to an abstract ID.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   PoolRecPtr   pointer to Pool table entry
  * @returns PoolID of entry
  */
@@ -143,6 +165,9 @@ static inline CFE_ES_MemHandle_t CFE_ES_MemPoolRecordGetID(const CFE_ES_MemPoolR
  * This sets the internal field(s) within this entry, and marks
  * it as being associated with the given Pool ID.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   PoolRecPtr   pointer to Pool table entry
  * @param[in]   PendingId    the Pool ID of this entry
  */
@@ -157,6 +182,9 @@ static inline void CFE_ES_MemPoolRecordSetUsed(CFE_ES_MemPoolRecord_t *PoolRecPt
  * This clears the internal field(s) within this entry, and allows the
  * memory to be re-used in the future.
  *
+ * @note This internal helper function must only be used on record pointers
+ * that are known to refer to an actual table location (i.e. non-null).
+ *
  * @param[in]   PoolRecPtr   pointer to Pool table entry
  */
 static inline void CFE_ES_MemPoolRecordSetFree(CFE_ES_MemPoolRecord_t *PoolRecPtr)
@@ -173,6 +201,16 @@ static inline void CFE_ES_MemPoolRecordSetFree(CFE_ES_MemPoolRecord_t *PoolRecPt
  * As this dereferences fields within the record, global data must be
  * locked prior to invoking this function.
  *
+ * This function may be used in conjunction with CFE_ES_LocateMemPoolRecordByID()
+ * to confirm that the located record is a positive match to the expected ID.
+ * As such, the record pointer is also permitted to be NULL, to alleviate the
+ * need for the caller to handle this possibility explicitly.
+ *
+ * Once a record pointer has been successfully validated using this routine,
+ * it may be safely passed to all other internal functions.
+ *
+ * @sa CFE_ES_LocateMemPoolRecordByID
+ *
  * @param[in]   PoolRecPtr   pointer to Pool table entry
  * @param[in]   PoolID       expected Pool ID
  * @returns true if the entry matches the given pool ID