api: promote sys/util.h to experimental

This file contains definitions for macros which are integral to
significant Zephyr use cases, such as CONTAINER_OF() and various
macros used by devicetree.h internally.

As such, in practice we expect at least advanced (if not intermediate)
users to understand it, so the fact that it's not formally documented
as an API with a stability level is a problem.

Fix that by giving the docstrings a once-over and adding new ones
where they are missing. Move all the remaining non-API macros to
util_internal.h.

Add a Sphinx API page for this header, and include it in the API
overview at "experimental" stability level.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

doc/reference/index.rst

@@ -30,4 +30,5 @@ API Reference
    storage/index.rst
    usb/index.rst
    usermode/index.rst
+   util/index.rst
    settings/index.rst

doc/reference/overview.rst

@@ -273,3 +273,8 @@ current :ref:`stability level <api_lifecycle>`.
      - Stable
      - 1.11
      - 1.11
+
+   * - :ref:`util_api`
+     - Experimental
+     - 2.4
+     - 2.4

doc/reference/util/index.rst

@@ -0,0 +1,10 @@
+.. _util_api:
+
+Utilities
+#########
+
+This page contains reference documentation for ``<sys/util.h>``, which provides
+miscellaneous utility functions and macros.
+
+.. doxygengroup:: sys-util
+   :project: Zephyr