docs: Prefer \ to @ in Doxygen comments

This commit replaces any instances of `@`-style Doxygen commands with their `\`-style equivalents. This is done for consistency across the codebase. The `\sa` Doxygen command has been added to the Clang-Format configuration to prevent it from reflowing see-also comments, which often exceed the column limit due to referring to long URLs. Change-Id: Ia4ebe8bd310293da9e2af55fe253f0762807e88a Signed-off-by: Chris Kay <[email protected]>
anukou · Oct 2, 2020 · 3361c32 · 3361c32
1 parent 8d2dafa
commit 3361c32
Show file tree

Hide file tree

Showing 118 changed files with 508 additions and 507 deletions.
diff --git a/.clang-format b/.clang-format
@@ -21,6 +21,7 @@ BreakBeforeBinaryOperators: None
 BreakBeforeBraces: WebKit
 BreakBeforeTernaryOperators: 'false'
 ColumnLimit: '80'
+CommentPragmas: '^\\sa'
 ContinuationIndentWidth: '4'
 Cpp11BracedListStyle: 'false'
 DerivePointerAlignment: 'false'

diff --git a/debugger/include/checkpoint.h b/debugger/include/checkpoint.h
@@ -12,7 +12,7 @@
 
 /*!
  * \addtogroup GroupCLIDebugger
- * @{
+ * \{
  */
 
 /*!
@@ -162,7 +162,7 @@ void checkpoint(checkpoint_st *c, char *file, int32_t line, char *tag);
 #endif
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* CHECKPOINT_H */
diff --git a/framework/include/fwk_arch.h b/framework/include/fwk_arch.h
@@ -17,12 +17,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupArch Architecture Interface
- * @{
+ * \{
  */
 
 /*!
@@ -215,11 +215,11 @@ struct fwk_arch_init_driver {
 int fwk_arch_init(const struct fwk_arch_init_driver *driver);
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_ARCH_H */
diff --git a/framework/include/fwk_cli_dbg.h b/framework/include/fwk_cli_dbg.h
@@ -11,12 +11,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupCLI Debugger
- * @{
+ * \{
  */
 
 #if defined(BUILD_HAS_DEBUGGER)
@@ -45,10 +45,10 @@
 #endif
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 #endif /* FWK_CLI_DBG_H */
diff --git a/framework/include/fwk_dlist.h b/framework/include/fwk_dlist.h
@@ -15,12 +15,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \addtogroup GroupLinkedList Linked Lists
- * @{
+ * \{
  */
 
 /*!
@@ -112,11 +112,11 @@ void __fwk_dlist_insert(
  */
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_DLIST_H */
diff --git a/framework/include/fwk_element.h b/framework/include/fwk_element.h
@@ -15,12 +15,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupElement Elements
- * @{
+ * \{
  */
 
 /*!
@@ -49,11 +49,11 @@ struct fwk_element {
 };
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_ELEMENT_H */
diff --git a/framework/include/fwk_event.h b/framework/include/fwk_event.h
@@ -21,12 +21,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupEvent Events
- * @{
+ * \{
  */
 
 /*!
@@ -99,11 +99,11 @@ struct fwk_event {
 };
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_EVENT_H */
diff --git a/framework/include/fwk_id.h b/framework/include/fwk_id.h
@@ -21,12 +21,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupId Identifiers
- * @{
+ * \{
  */
 
 /*!
@@ -589,11 +589,11 @@ struct fwk_id_verbose_fmt {
 struct fwk_id_verbose_fmt fwk_id_verbose_str(fwk_id_t id);
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_ID_H */
diff --git a/framework/include/fwk_interrupt.h b/framework/include/fwk_interrupt.h
@@ -19,12 +19,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupInterrupt Interrupt Management
- * @{
+ * \{
  */
 
 /*!
@@ -200,11 +200,11 @@ int fwk_interrupt_set_isr_param(unsigned int interrupt,
 int fwk_interrupt_get_current(unsigned int *interrupt);
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_INTERRUPT_H */
diff --git a/framework/include/fwk_list.h b/framework/include/fwk_list.h
@@ -19,12 +19,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \addtogroup GroupLinkedList Linked Lists
- * @{
+ * \{
  */
 
 /*!
@@ -219,11 +219,11 @@
         elem = FWK_LIST_GET(node, type, member))
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_LIST_H */
diff --git a/framework/include/fwk_macros.h b/framework/include/fwk_macros.h
@@ -13,12 +13,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupMacros Macros
- * @{
+ * \{
  */
 
 /*!
@@ -370,11 +370,11 @@
 #endif
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_MACROS_H */
diff --git a/framework/include/fwk_math.h b/framework/include/fwk_math.h
@@ -18,7 +18,7 @@
  * \details Math helper functions to implement several common operations in an
  *      efficient way.
  *
- * @{
+ * \{
  */
 
 /*!
@@ -64,7 +64,7 @@
     ((sizeof(num) * CHAR_BIT) - fwk_math_clz(num) - 1)
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_MATH_H */
diff --git a/framework/include/fwk_module.h b/framework/include/fwk_module.h
@@ -21,12 +21,12 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupModule Modules
- * @{
+ * \{
  */
 
 /*!
@@ -581,11 +581,11 @@ int fwk_module_adapter(const struct fwk_io_adapter **adapter, fwk_id_t id);
 void fwk_module_init(void);
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_MODULE_H */
diff --git a/framework/include/fwk_multi_thread.h b/framework/include/fwk_multi_thread.h
@@ -15,13 +15,13 @@
 
 /*!
  * \addtogroup GroupLibFramework Framework
- * @{
+ * \{
  */
 
 /*!
  * \defgroup GroupThread Threading
  *
- * @{
+ * \{
  */
 
 /*!
@@ -94,11 +94,11 @@ int fwk_thread_put_event_and_wait(
 #endif
 
 /*!
- * @}
+ * \}
  */
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_MULTI_THREAD_H */
diff --git a/framework/include/fwk_notification.h b/framework/include/fwk_notification.h
@@ -22,7 +22,7 @@
 /*!
  * \ingroup GroupLibFramework
  * \defgroup GroupNotification Notifications
- * @{
+ * \{
  */
 
 /*!
@@ -94,7 +94,7 @@ int fwk_notification_notify(struct fwk_event *notification_event,
                             unsigned int *count);
 
 /*!
- * @}
+ * \}
  */
 
 #endif /* FWK_NOTIFICATION_H */