doc: reference: add a page for iterable sections

Group together the iterable section functions and add a corresponding
documentation page.

Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>

doc/reference/index.rst

@@ -16,6 +16,7 @@ API Reference
    display/index.rst
    edac/index.rst
    file_system/index.rst
+   iterable_sections/index.rst
    misc/formatted_output.rst
    kernel/index.rst
    libc/index.rst

doc/reference/iterable_sections/index.rst

@@ -0,0 +1,10 @@
+.. _iterable_sections_api:
+
+Iterable Sections
+#################
+
+This page contains the reference documentation for the iterable sections APIs,
+which can be used for defining iterable areas of equally-sized data structures,
+that can be iterated on using `STRUCT_SECTION_FOREACH()`.
+
+.. doxygengroup:: iterable_section_apis

include/linker/linker-defs.h

@@ -38,6 +38,12 @@
 #endif
 
 #ifdef _LINKER
+
+/**
+ * @addtogroup iterable_section_apis
+ * @{
+ */
+
 #define Z_LINK_ITERABLE(struct_type) \
 	_CONCAT(_##struct_type, _list_start) = .; \
 	KEEP(*(SORT_BY_NAME(._##struct_type.static.*))); \
@@ -141,6 +147,10 @@
 		Z_LINK_ITERABLE_GC_ALLOWED(struct_type); \
 	} GROUP_DATA_LINK_IN(RAMABLE_REGION, ROMABLE_REGION)
 
+/**
+ * @}
+ */ /* end of struct_section_apis */
+
 /*
  * generate a symbol to mark the start of the objects array for
  * the specified object and level, then link all of those objects

include/toolchain/common.h

@@ -179,6 +179,12 @@
  */
 #define Z_DECL_ALIGN(type) __aligned(__alignof(type)) type
 
+/**
+ * @brief Iterable Sections APIs
+ * @defgroup iterable_section_apis Iterable Sections APIs
+ * @{
+ */
+
 /**
  * @brief Defines a new iterable section.
  *
@@ -235,4 +241,8 @@
 		iterator < _CONCAT(_##struct_type, _list_end); }); \
 	     iterator++)
 
+/**
+ * @}
+ */ /* end of struct_section_apis */
+
 #endif /* ZEPHYR_INCLUDE_TOOLCHAIN_COMMON_H_ */