Update OS_ObjectIdToArrayIndex documentation related to it being an API, inconsistent documentation in implementation

[skliper]

Is your feature request related to a problem? Please describe.
'OS_ObjectIdToArrayIndex is an external API:

osal/src/os/inc/osapi-idmap.h

Lines 203 to 232 in 706f0de

	/*-------------------------------------------------------------------------------------*/
	/**
	* @brief Converts an abstract ID into a number suitable for use as an array index.
	*
	* This will return a unique zero-based integer number in the range of [0,MAX) for
	* any valid object ID. This may be used by application code as an array index
	* for indexing into local tables.
	*
	* This routine operates on a specific object type, and returns a value based on the
	* maximum number of objects for that type.
	*
	* If the idtype is passed as #OS_OBJECT_TYPE_UNDEFINED, then object type verification
	* is skipped and any object ID will be accepted and converted to an index. In this
	* mode, the range of the output depends on the actual passed-in object type.
	*
	* If the idtype is passed as any other value, the passed-in ID value is first
	* confirmed to be the correct type. This check will guarantee that the output
	* is within an expected range; for instance, if the type is passed as
	* #OS_OBJECT_TYPE_OS_TASK, then the output index is guaranteed to be between 0 and
	* #OS_MAX_TASKS-1 after successful conversion.
	*
	* @param[in] idtype The object type to convert
	* @param[in] object_id The object ID to operate on
	* @param[out] *ArrayIndex The Index to return
	*
	* @return Execution status, see @ref OSReturnCodes
	* @retval #OS_SUCCESS @copybrief OS_SUCCESS
	* @retval #OS_ERR_INCORRECT_OBJ_TYPE @copybrief OS_ERR_INCORRECT_OBJ_TYPE
	* */
	int32 OS_ObjectIdToArrayIndex(osal_objtype_t idtype, osal_id_t object_id, osal_index_t *ArrayIndex);

Yet internally there's a few style patterns and references that treat it like it's internal:

osal/src/os/shared/src/osapi-idmap.c

Lines 1529 to 1543 in 706f0de

	/*----------------------------------------------------------------
	*
	* Function: OS_ObjectIdToArrayIndex
	*
	* Purpose: Convert an object ID (which must be of the given type) to a number suitable
	* for use as an array index. The array index will be in the range of:
	* 0 <= ArrayIndex < OS_MAX_<OBJTYPE>
	*
	* If the passed-in ID type is OS_OBJECT_TYPE_UNDEFINED, then any type
	* is allowed.
	*
	* returns: If the passed-in ID is not of the proper type, OS_ERROR is returned
	* Otherwise OS_SUCCESS is returned.
	*
	*-----------------------------------------------------------------*/

osal/src/os/shared/src/osapi-idmap.c

Line 1413 in 706f0de

/* just pass to the generic internal conversion routine */

Note the implementation file itself has some inconsistencies:

osal/src/os/shared/src/osapi-idmap.c

Lines 41 to 42 in 706f0de

	* NOTE: The only exception is OS_ConvertToArrayIndex() as this is necessary to
	* assist applications when storing OSAL IDs in a table.

osal/src/os/shared/src/osapi-idmap.c

Lines 129 to 133 in 706f0de

	/*
	*********************************************************************************
	* IDENTIFIER MAP / UNMAP FUNCTIONS
	*********************************************************************************
	*/

osal/src/os/shared/src/osapi-idmap.c

Lines 135 to 142 in 706f0de

	/*----------------------------------------------------------------
	*
	* Function: OS_ObjectIdInit
	*
	* Purpose: Local helper routine, not part of OSAL API.
	* clears the entire table and brings it to a proper initial state
	*
	*-----------------------------------------------------------------*/

osal/src/os/shared/src/osapi-idmap.c

Lines 230 to 233 in 706f0de

	/**************************************************************
	* LOCAL HELPER FUNCTIONS
	* (not used outside of this unit)
	**************************************************************/

Describe the solution you'd like
Update comments, make sure headers are in the right place

Describe alternatives you've considered
None

Additional context
None

Requester Info
Jacob Hageman - NASA/GSFC

[jphickey]

If I remember correctly, this originally was an internal routine, but it was deemed useful because it actually confirms the object ID is of the expected/intended object type, unlike OS_ConvertToArrayIndex which will accept any object type. The latter was not removed/deprecated though, since it is an easy drop-in to fix legacy code which used osal ID as an array index directly. But new code should prefer the better error checking provided by OS_ObjectIdToArrayIndex.