Fix all sorts of errors and warnings in the documentation

Broken/missing references, wrong directives etc.

cmake/modules/DuneDoc.cmake

@@ -36,9 +36,9 @@
 #
 # .. cmake_function:: create_doc_install
 #
-#    .. todo::
+#    TODO doc me
+#    What are use cases for this function?
 #
-#       Evaluate use cases for this function.
 
 FIND_PACKAGE(LATEX)
 FIND_PROGRAM(IMAGEMAGICK_CONVERT convert

cmake/modules/DuneEnableAllPackages.cmake

@@ -35,11 +35,11 @@
 #
 #       If your module contains libraries as well as programs and if the programs should automatically
 #       link to those libraries, you *MUST* list these libraries in :code:`MODULE_LIBRARIES`. Those libraries will be
-#       automatically created by :ref:`dune_enable_all_packages` (which internally calls :ref:`dune_add_library()`) and placed
+#       automatically created by :ref:`dune_enable_all_packages` (which internally calls :ref:`dune_add_library`) and placed
 #       in the lib/ directory. The order of the libraries matters: if one library depends on another one, it must
 #       be listed after its dependency. This special handling of the libraries is due to the way newer CMake
 #       versions handle linking (in particular CMP022 and CMP038). You can later add source files to the library
-#       anywhere in the source tree by calling :ref:`dune_library_add_sources()`.
+#       anywhere in the source tree by calling :ref:`dune_library_add_sources`.
 #
 #       .. warning::
 #          The library feature requires CMake 3.1+. If you use the feature with older versions, CMake

cmake/modules/DuneSymlinkOrCopy.cmake

@@ -35,8 +35,7 @@
 #       :single:
 #       :required:
 #
-#    .. todo::
-#       DOC ME!
+#    TODO DOC ME!
 #
 # .. cmake_function:: dune_add_copy_target
 #
@@ -50,8 +49,7 @@
 #       :single:
 #       :required:
 #
-#    .. todo::
-#       DOC ME!
+#    TODO DOC ME!
 #
 # .. cmake_function:: dune_add_copy_dependency
 #
@@ -65,8 +63,7 @@
 #       :single:
 #       :required:
 #
-#    .. todo::
-#       DOC ME!
+#    TODO DOC ME!
 #
 # .. cmake_function:: dune_symlink_to_source_tree
 #

cmake/modules/FindMETIS.cmake

@@ -8,7 +8,7 @@
 #    :ref:`METIS_ROOT`
 #       Prefix, where METIS is installed
 #
-#    :ref:`METIS_LIBNAME`
+#    :ref:`METIS_LIB_NAME`
 #       Name of the METIS library (default: metis)
 #
 #    :ref:`METIS_LIBRARY`
@@ -31,7 +31,7 @@
 #   for the METIS library and includes in the given path
 #   before inspecting default system paths.
 #
-# .. cmake_variable:: METIS_LIBNAME
+# .. cmake_variable:: METIS_LIB_NAME
 #
 #   You may set this variable to specify the name of the METIS
 #   library that :ref:`FindMETIS` looks for.

cmake/modules/FindPTScotch.cmake

@@ -29,6 +29,21 @@
 #    :code:`PTSCOTCH_FOUND`
 #       True if PT-Scotch was found.
 #
+# .. cmake_variable:: PTSCOTCH_ROOT
+#
+#   You may set this variable to have :ref:`FindPTScotch` look
+#   for the PTScotch package in the given path before inspecting
+#   system paths.
+#
+# .. cmake_variable:: PTSCOTCH_SUFFIX
+#
+#   PTScotch might be compiled using different
+#   integer sizes (int32, int64, long). When
+#   this is is set the headers and libaries
+#   are search under the suffix
+#   :code:`include/scotch-${PTSCOTCH_SUFFIX}`, and
+#   :code:`lib/scotch-${PTSCOTCH_SUFFIX}`, respectively.
+#
 
 include(DuneMPI)
 macro(_search_pt_lib libvar libname doc)

cmake/modules/FindThreadsCMake31.cmake

@@ -25,12 +25,12 @@
 # .. cmake_variable:: CMAKE_THREAD_PREFER_PTHREAD
 #
 #    For systems with multiple thread libraries, caller can set this
-#    variable to prefer pthread. Modifies the behaviour of :ref:`FindThreadsCMake31.cmake`.
+#    variable to prefer pthread. Modifies the behaviour of :ref:`FindThreadsCMake31`.
 #
 # .. cmake_variable:: THREADS_PREFER_PTHREAD_FLAG
 #
 #    If the use of the -pthread compiler and linker flag is prefered then the
-#    caller can set this variable. Modifies the behaviour of :ref:`FindThreadsCMake31.cmake`.
+#    caller can set this variable. Modifies the behaviour of :ref:`FindThreadsCMake31`.
 #
 
 #=============================================================================

cmake/modules/UseInkscape.cmake

@@ -20,9 +20,7 @@
 #
 #       dpi value for the generated image (default: 90)
 #
-#    .. todo::
-#
-#       Switch to named arguments!
+#    TODO Switch to named arguments!
 #
 
 include(CMakeParseArguments)