[cmake-developers] [PATCH] Better find module developer documentation

[Brad King]

On 03/26/2014 03:02 PM, Alex Merry wrote:
> I wrote some documentation on how to write a find module for KDE's
> extra-cmake-modules project, and Stephen suggested upstreaming it.  So
> attached is a patch that does that.

Thanks for working on this.  I like the tutorial-style presentation.

First, a few reST style comments:

* Paragraphs ending in ": ::" can be simplified to "::".

* CMake code blocks should use ".. code-block:: cmake" rather
  than a plain literal block if the code in the block is valid
  CMake code (as against containing placeholders as in command
  signature documentation).

* Indented blocks where the amount of indentation can be chosen
  should use 2 spaces instead of 1.

> Note that this changes the recommendations from the Foo_LIBRARIES,
> Foo_INCLUDES and Foo_DEFINITIONS variables to creating imported targets
> (which are much easier and less error-prone to use).

Providing imported targets is nice, and preferred by KDE, but is
not a requirement for upstream modules.  Most existing modules
have not been updated to provide them.  Using imported targets
throughout a project requires additional effort when creating
package configuration files to ensure dependencies that name
imported targets have them available.

The docs should explain both approaches.  Then explain why
imported targets are preferred but that since the approach
is newer not all existing modules have been updated.

We need to maintain the list of example variable names.  The
difference between Foo_LIBRARY and Foo_LIBRARIES needs to be
clearly explained, and not just in the sample module section.

Thanks,
-Brad