API dox: turn some more verbal "Note" into full note sections

Should help readers being aware of pitfalls

NO_CHANGELOG

7 files changed, 27 insertions, 19 deletions

diff --git a/kde-modules/KDECMakeSettings.cmake b/kde-modules/KDECMakeSettings.cmake
index 8950cfb1..d2d06b18 100644
--- a/kde-modules/KDECMakeSettings.cmake
+++ b/kde-modules/KDECMakeSettings.cmake
@@ -27,9 +27,10 @@ dynamically-linked libraries) is set to include the location that libraries
 will be installed to (as set in ``LIB_INSTALL_DIR`` or, if the former is not set,
 ``KDE_INSTALL_LIBDIR``), and also the linker search path.
 
-Note that ``LIB_INSTALL_DIR`` or alternatively ``KDE_INSTALL_LIBDIR`` needs
-to be set before including this module.
-Typically, this is done by including the :kde-module:`KDEInstallDirs` module.
+.. note::
+  ``LIB_INSTALL_DIR`` or alternatively ``KDE_INSTALL_LIBDIR`` needs
+  to be set before including this module.
+  Typically, this is done by including the :kde-module:`KDEInstallDirs` module.
 
 This section can be disabled by setting ``KDE_SKIP_RPATH_SETTINGS`` to ``TRUE``
 before including this module.
diff --git a/kde-modules/KDECompilerSettings.cmake b/kde-modules/KDECompilerSettings.cmake
index ceb313ac..08881507 100644
--- a/kde-modules/KDECompilerSettings.cmake
+++ b/kde-modules/KDECompilerSettings.cmake
@@ -19,8 +19,9 @@ for some compiler features.  By default, exceptions are disabled;
 ``kde_target_enable_exceptions()`` can be used to re-enable them for a
 specific target.
 
-NB: it is recommended to include this module with the ``NO_POLICY_SCOPE``
-flag, otherwise you may get spurious warnings with some versions of CMake.
+.. note::
+  It is recommended to include this module with the ``NO_POLICY_SCOPE``
+  flag, otherwise you may get spurious warnings with some versions of CMake.
 
 Since 5.85 newer settings are controlled by a variable
 ``KDE_COMPILERSETTINGS_LEVEL``, taking an ECM version as value. That
diff --git a/kde-modules/KDEFrameworkCompilerSettings.cmake b/kde-modules/KDEFrameworkCompilerSettings.cmake
index 73b0cff5..bbe38026 100644
--- a/kde-modules/KDEFrameworkCompilerSettings.cmake
+++ b/kde-modules/KDEFrameworkCompilerSettings.cmake
@@ -23,8 +23,9 @@ For example, constructions like ``QString("foo")`` are prohibited, instead
 forcing the use of QLatin1String or QStringLiteral, and some
 Qt-defined keywords like signals and slots will not be defined.
 
-NB: it is recommended to include this module with the NO_POLICY_SCOPE
-flag, otherwise you may get spurious warnings with some versions of CMake.
+.. note::
+  It is recommended to include this module with the NO_POLICY_SCOPE
+  flag, otherwise you may get spurious warnings with some versions of CMake.
 
 Since pre-1.0.0.
 #]=======================================================================]
diff --git a/modules/ECMCoverageOption.cmake b/modules/ECMCoverageOption.cmake
index 6109fd65..30b2c82a 100644
--- a/modules/ECMCoverageOption.cmake
+++ b/modules/ECMCoverageOption.cmake
@@ -16,7 +16,8 @@ When this module is included, a ``BUILD_COVERAGE`` option is added (default
 ``OFF``). Turning this option on enables GCC's coverage instrumentation, and
 links against ``libgcov``.
 
-Note that this will probably break the build if you are not using GCC.
+.. note::
+  This will probably break the build if you are not using GCC.
 
 Since 1.3.0.
 #]=======================================================================]
diff --git a/modules/ECMFindModuleHelpers.cmake b/modules/ECMFindModuleHelpers.cmake
index 1375ebd4..a4837403 100644
--- a/modules/ECMFindModuleHelpers.cmake
+++ b/modules/ECMFindModuleHelpers.cmake
@@ -93,11 +93,12 @@ The following variables will be set:
   they are passed to the macro), although if it is already set, it will not
   be altered
 
-Note that these variables are never cleared, so if
-``ecm_find_package_handle_library_components()`` is called multiple times with
-different components (typically because of multiple ``find_package()`` calls) then
-``<name>_TARGETS``, for example, will contain all the targets found in any
-call (although no duplicates).
+.. note::
+  These variables are never cleared, so if
+  ``ecm_find_package_handle_library_components()`` is called multiple times with
+  different components (typically because of multiple ``find_package()`` calls) then
+  ``<name>_TARGETS``, for example, will contain all the targets found in any
+  call (although no duplicates).
 
 Since pre-1.0.0.
 #]=======================================================================]
diff --git a/modules/ECMGenerateDBusServiceFile.cmake b/modules/ECMGenerateDBusServiceFile.cmake
index f3c7dd8a..6efdd95d 100644
--- a/modules/ECMGenerateDBusServiceFile.cmake
+++ b/modules/ECMGenerateDBusServiceFile.cmake
@@ -26,8 +26,9 @@ in the relevant D-Bus config location. This filename can be customized with RENA
 ``<executable>`` must be an absolute path to the installed service executable. When using it with
 :kde-module:`KDEInstallDirs` it needs to be the ``_FULL_`` variant of the path variable.
 
-Note: On Windows, the macro will only use the file name part of ``<executable>`` since D-Bus
-service executables are to be installed in the same directory as the D-Bus daemon.
+.. note::
+  On Windows, the macro will only use the file name part of ``<executable>`` since D-Bus
+  service executables are to be installed in the same directory as the D-Bus daemon.
 
 Optionally, a ``<systemd service>`` can be specified to launch the corresponding
 systemd service instead of the ``<executable>`` if the D-Bus daemon is started by systemd.
diff --git a/modules/ECMGeneratePkgConfigFile.cmake b/modules/ECMGeneratePkgConfigFile.cmake
index 1b59da8d..c556e31e 100644
--- a/modules/ECMGeneratePkgConfigFile.cmake
+++ b/modules/ECMGeneratePkgConfigFile.cmake
@@ -65,10 +65,12 @@ package. Defaults to "https://www.kde.org/". Since 5.89.0.
 
 ``INSTALL`` will cause the module to be installed to the ``pkgconfig``
 subdirectory of ``LIB_INSTALL_DIR``, unless the ``ECM_PKGCONFIG_INSTALL_DIR``
-cache variable is set to something different. Note that the first call to
-``ecm_generate_pkgconfig_file()`` with the ``INSTALL`` argument will cause
-``ECM_PKGCONFIG_INSTALL_DIR`` to be set to the cache, and will be used in any
-subsequent calls.
+cache variable is set to something different.
+
+.. note::
+  The first call to ``ecm_generate_pkgconfig_file()`` with the ``INSTALL``
+  argument will cause ``ECM_PKGCONFIG_INSTALL_DIR`` to be set to the cache,
+  and will be used in any subsequent calls.
 
 To properly use this macro a version needs to be set. To retrieve it,
 ``ECM_PKGCONFIG_INSTALL_DIR`` uses ``PROJECT_VERSION``. To set it, use the