From 74f1fbb7a173faa5b17f05d15a161dda63901a8f Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 7 Dec 2021 12:29:47 -0500 Subject: Help/dev: Cover module function naming in CMake Documentation Guide --- Help/dev/documentation.rst | 61 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 4 deletions(-) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 4a2a5d9..db92022 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -513,7 +513,7 @@ bracket is excluded if and only if the line starts in ``#``. Additional such ``.rst:`` comments may appear anywhere in the module file. All such comments must start with ``#`` in the first column. -For example, a ``Findxxx.cmake`` module may contain: +For example, a ``FindXxx.cmake`` module may contain: :: @@ -540,13 +540,13 @@ For example, a ``Findxxx.cmake`` module may contain: #[=======================================================================[.rst: - .. command:: xxx_do_something + .. command:: Xxx_do_something This command does something for Xxx:: - xxx_do_something(some arguments) + Xxx_do_something(some arguments) #]=======================================================================] - macro(xxx_do_something) + macro(Xxx_do_something) endmacro() @@ -559,3 +559,56 @@ documentation, simply leave out the ``Help/module/.rst`` file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment + +Module Functions and Macros +--------------------------- + +Modules may provide CMake functions and macros defined by the `function()`_ +and `macro()`_ commands. To avoid conflicts across modules, name the +functions and macros using the prefix ``_`` followed by the +rest of the name, where ```` is the exact-case spelling of +the module name. We have no convention for the portion of names after +the ``_`` prefix. + +For historical reasons, some modules that come with CMake do not follow +this prefix convention. When adding new functions to these modules, +discussion during review can decide whether to follow their existing +convention or to use the module name prefix. + +Documentation of public functions and macros should be provided in +the module, typically in the main `module documentation`_ at the top. +For example, a ``MyModule`` module may document a function like this:: + + #[=======================================================================[.rst: + MyModule + -------- + + This is my module. It provides some functions. + + .. command:: MyModule_Some_Function + + This is some function: + + .. code-block:: cmake + + MyModule_Some_Function(...) + #]=======================================================================] + +Documentation may alternatively be placed just before each definition. +For example, a ``MyModule`` module may document another function like this:: + + #[=======================================================================[.rst: + .. command:: MyModule_Other_Function + + This is another function: + + .. code-block:: cmake + + MyModule_Other_Function(...) + #]=======================================================================] + function(MyModule_Other_Function ...) + # ... + endfunction() + +.. _`function()`: https://cmake.org/cmake/help/latest/command/function.html +.. _`macro()`: https://cmake.org/cmake/help/latest/command/macro.html -- cgit v0.12