Merge doxygen patch into v1.4.0 version (#186)

* Enable typedef to make docs able to link *_t structs. (#185) * Replace Synopsys link with blackduck one to solve link error. (#180) * Fix freertos.org link in the source and doxygen files (#177) --------- Co-authored-by: chinglee-iot <[email protected]>
FreeRTOS · Dec 11, 2024 · 82ec945 · 82ec945
1 parent 4301355
commit 82ec945
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 20 deletions.
diff --git a/docs/doxygen/config.doxyfile b/docs/doxygen/config.doxyfile
@@ -299,7 +299,7 @@ ALIASES                = "dependencies_section{1}=@section \1_dependencies Depen
                          "enums_brief{1}=@brief Enumerated types of the \1." \
                          "functionpointers_group{2}=@defgroup \1_datatypes_functionpointers \2 Function pointer types" \
                          "functionpointers_brief{1}=@brief Function pointer types of the \1." \
-                         "structs_group{21}=@defgroup \1_datatypes_structs \2 Structured types" \
+                         "structs_group{2}=@defgroup \1_datatypes_structs \2 Structured types" \
                          "structs_brief{1}=@brief Structured types of the \1." \
                          "paramstructs_group{2}=@defgroup \1_datatypes_paramstructs \2 Parameter structures" \
                          "paramstructs_brief{2}=@brief Structures passed as parameters to [\2 functions](@ref \1_functions)<br>These structures are passed as parameters to library functions. Documentation for these structures will state the functions associated with each parameter structure and the purpose of each member." \
@@ -478,7 +478,7 @@ INLINE_SIMPLE_STRUCTS  = NO
 # types are typedef'ed and only the typedef is referenced, never the tag name.
 # The default value is: NO.
 
-TYPEDEF_HIDES_STRUCT   = YES
+TYPEDEF_HIDES_STRUCT   = NO
 
 # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
 # cache is used to resolve symbols given their name and scope. Since this can be

diff --git a/docs/doxygen/pages.dox b/docs/doxygen/pages.dox
@@ -366,14 +366,14 @@ bool PlatformMutex_TryLock( PlatformMutex_t * pMutex );
 void PlatformMutex_Unlock( PlatformMutex_t * pMutex );
 ```
  - <b>Memory</b><br>The following malloc/free style APIs should be provided in cellular_platform.h.<br>
- The <a href="https://www.freertos.org/a00111.html">FreeRTOS memory management document</a> can be referenced for these APIs.
+ The <a href="https://freertos.org/Documentation/02-Kernel/02-Kernel-features/09-Memory-management/01-Memory-management">FreeRTOS memory management document</a> can be referenced for these APIs.
 ```
 // Example implementation of FreeRTOS malloc/free
 #define Platform_Malloc    pvPortMalloc
 #define Platform_Free      vPortFree
 ```
  - <b>EventGroup</b><br>The following APIs and handle should be provided in cellular_platform.h.<br>
- Please reference <a href="https://www.freertos.org/event-groups-API.html">FreeRTOS EvengGroup function prototypes</a>.
+ Please reference <a href="https://freertos.org/Documentation/02-Kernel/04-API-references/12-Event-groups-or-flags/00-Event-groups">FreeRTOS EvengGroup function prototypes</a>.
 ```
 // Example implementation of FreeRTOS EvengGroup
 #define PlatformEventGroupHandle_t           EventGroupHandle_t
@@ -387,7 +387,7 @@ void PlatformMutex_Unlock( PlatformMutex_t * pMutex );
 #define PlatformEventGroup_WaitBits          xEventGroupWaitBits
 ```
  - <b>Queue</b><br>The following APIs and handle should be provided in cellular_platform.h.<br>
- Please reference <a href="https://freertos.org/a00018.html">FreeRTOS Queue function prototypes</a>.
+ Please reference <a href="https://freertos.org/Documentation/02-Kernel/04-API-references/06-Queues/00-QueueManagement">FreeRTOS Queue function prototypes</a>.
 ```
 // Example implementation of FreeRTOS Queue
 #define PlatformQueueHandle_t    QueueHandle_t
@@ -397,13 +397,18 @@ void PlatformMutex_Unlock( PlatformMutex_t * pMutex );
 #define PlatformQueue_Delete     vQueueDelete
 ```
  - <b>Delay</b><br>The following API should be provided in cellular_platform.h.<br>
- Please reference <a href="https://www.freertos.org/a00127.html">FreeRTOS Task Control function prototypes</a>.
+ Please reference <a href="https://freertos.org/Documentation/02-Kernel/04-API-references/02-Task-control/00-Task-control">FreeRTOS Task Control function prototypes</a>.
 ```
 // Example implementation of FreeRTOS Task Control
 #define Platform_Delay( delayMs )           vTaskDelay( pdMS_TO_TICKS( delayMs ) )
 ```
 */
 
+/**
+ * @structs_group{cellular,Cellular}
+ * @structs_brief{cellular,cellular}
+ */
+
 /**
  * @paramstructs_group{cellular,Cellular}
  * @paramstructs_brief{cellular,cellular}
@@ -423,3 +428,8 @@ void PlatformMutex_Unlock( PlatformMutex_t * pMutex );
  * @enums_group{cellular,Cellular}
  * @enums_brief{cellular library}
  */
+
+/**
+ * @common_datatypes_paramstructs_group{cellular,Cellular}
+ * @common_datatypes_paramstructs_brief{cellular library}
+ */
diff --git a/source/include/cellular_types.h b/source/include/cellular_types.h
@@ -54,10 +54,6 @@
  */
 #define CELLULAR_INVALID_SIGNAL_BAR_VALUE    ( 0xFFU )
 
-/**
- * @ingroup cellular_datatypes_handles
- * @brief Opaque Cellular context structure.
- */
 struct CellularContext;
 
 /**

diff --git a/source/include/common/cellular_common.h b/source/include/common/cellular_common.h
@@ -55,7 +55,7 @@
 /*-----------------------------------------------------------*/
 
 /**
- * @ingroup cellular_common_datatypes_paramstructs
+ * @ingroup cellular_datatypes_paramstructs
  * @brief The AT command request structure.
  */
 typedef struct CellularAtReq
@@ -69,7 +69,7 @@ typedef struct CellularAtReq
 } CellularAtReq_t;
 
 /**
- * @ingroup cellular_common_datatypes_paramstructs
+ * @ingroup cellular_datatypes_paramstructs
  * @brief The data command request structure.
  */
 typedef struct CellularAtDataReq
@@ -94,7 +94,7 @@ typedef void ( * CellularAtParseTokenHandler_t )( CellularContext_t * pContext,
                                                   char * pInputStr );
 
 /**
- * @ingroup cellular_common_datatypes_paramstructs
+ * @ingroup cellular_datatypes_paramstructs
  * @brief the URC token and URC handler mapping structure used by pkthandler.
  */
 typedef struct CellularAtParseTokenMap
@@ -116,7 +116,7 @@ typedef enum CellularSocketState
 } CellularSocketState_t;
 
 /**
- * @ingroup cellular_common_datatypes_paramstructs
+ * @ingroup cellular_datatypes_paramstructs
  * @brief Parameters involved in sending/receiving data through sockets.
  */
 typedef struct CellularSocketContext
@@ -151,7 +151,7 @@ typedef struct CellularSocketContext
 } CellularSocketContext_t;
 
 /**
- * @ingroup cellular_common_datatypes_paramstructs
+ * @ingroup cellular_datatypes_paramstructs
  * @brief Parameters to setup pktio and pkthandler token tables.
  */
 typedef struct CellularTokenTable

diff --git a/source/interface/cellular_comm_interface.h b/source/interface/cellular_comm_interface.h
@@ -151,6 +151,7 @@ typedef CellularCommInterfaceError_t ( * CellularCommInterfaceRecv_t )( Cellular
 typedef CellularCommInterfaceError_t ( * CellularCommInterfaceClose_t )( CellularCommInterfaceHandle_t commInterfaceHandle );
 
 /**
+ * @ingroup cellular_datatypes_paramstructs
  * @brief Represents the functions of a comm interface.
  *
  * Functions of these signature should be implemented against a comm interface

diff --git a/test/cbmc/include/cellular_platform.h b/test/cbmc/include/cellular_platform.h
@@ -41,7 +41,7 @@
  * Cellular library use platform event group for process synchronization.
  *
  * The EventGroup functions in the following link can be referenced as function prototype.
- * https://www.freertos.org/event-groups-API.html
+ * https://freertos.org/Documentation/02-Kernel/04-API-references/12-Event-groups-or-flags/00-Event-groups
  *
  */
 
@@ -236,7 +236,7 @@ uint16_t PlatformEventGroup_GetBits( PlatformEventGroupHandle_t groupEvent );
  *
  * Cellular library use platform memory allocation APIs to allocate memory dynamically.
  * The FreeRTOS memory management document can be referenced for these APIs.
- * https://www.freertos.org/a00111.html
+ * https://freertos.org/Documentation/02-Kernel/02-Kernel-features/09-Memory-management/01-Memory-management
  *
  */
 

diff --git a/test/unit-test/cellular_platform.h b/test/unit-test/cellular_platform.h
@@ -78,7 +78,7 @@
  *
  * Cellular library use platform memory allocation APIs to allocate memory dynamically.
  * The FreeRTOS memory management document can be referenced for these APIs.
- * https://www.freertos.org/a00111.html
+ * https://freertos.org/Documentation/02-Kernel/02-Kernel-features/09-Memory-management/01-Memory-management
  *
  */
 
@@ -205,7 +205,7 @@ bool Platform_CreateDetachedThread( void ( * threadRoutine )( void * pArgument )
  * Cellular library use platform event group for process synchronization.
  *
  * The EventGroup functions in the following link can be referenced as function prototype.
- * https://www.freertos.org/event-groups-API.html
+ * https://freertos.org/Documentation/02-Kernel/04-API-references/12-Event-groups-or-flags/00-Event-groups
  *
  */
 bool PlatformMutex_Create( PlatformMutex_t * pNewMutex,

diff --git a/tools/coverity/README.md b/tools/coverity/README.md
@@ -12,7 +12,7 @@ see the [MISRA.md](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/blob/
 
 ## Getting Started
 ### Prerequisites
-You can run this on a platform supported by Coverity. The list and other details can be found [here](https://sig-docs.synopsys.com/polaris/topics/c_coverity-compatible-platforms.html).
+You can run this on a platform supported by Coverity. The list and other details can be found [here](https://documentation.blackduck.com/bundle/coverity-docs/page/deploy-install-guide/topics/supported_platforms_for_coverity_analysis.html).
 To compile and run the Coverity target successfully, you must have the following:
 
 1. CMake version > 3.13.0 (You can check whether you have this by typing `cmake --version`)