simplify doxygen input path

reduce warnings from thousands to hundreds as long as major code is undocumented
fix displayed include paths in doxygen output
fix some of the warnings

doc/doxygen/CMakeLists.txt

@@ -90,32 +90,42 @@ ADD_CUSTOM_COMMAND(
 # Finalize the doxygen configuration:
 #
 file(GLOB _doxygen_input
+  ${CMAKE_CURRENT_BINARY_DIR}/tutorial/*.h
+  )
+LIST(APPEND _doxygen_input
+  ${CMAKE_SOURCE_DIR}/include/
+  ${CMAKE_BINARY_DIR}/include/
+  ${CMAKE_CURRENT_SOURCE_DIR}/headers/
+  ${CMAKE_SOURCE_DIR}/doc/news/
+  ${CMAKE_CURRENT_BINARY_DIR}/tutorial/tutorial.h
+  ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/
+  )
+TO_STRING(_doxygen_input_string ${_doxygen_input})
+
+SET(_doxygen_image_path
+  ${CMAKE_CURRENT_SOURCE_DIR}/images
+  ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/images
+  ${CMAKE_CURRENT_BINARY_DIR}/images
+  )
+TO_STRING(_doxygen_image_path_string ${_doxygen_image_path})
+
+file(GLOB _doxygen_depend
   ${CMAKE_CURRENT_SOURCE_DIR}/headers/*.h
   ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/*.h
   ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/main.cpp
   ${CMAKE_SOURCE_DIR}/doc/news/*.h
   ${CMAKE_SOURCE_DIR}/include/deal.II/**/*.h
   )
-LIST(APPEND _doxygen_input
+LIST(APPEND _doxygen_depend
   ${CMAKE_BINARY_DIR}/include/deal.II/base/config.h
   ${CMAKE_CURRENT_BINARY_DIR}/tutorial/tutorial.h
   )
 FOREACH(_step ${DEAL_II_STEPS})
   GET_FILENAME_COMPONENT(_step "${_step}" NAME)
-  LIST(APPEND _doxygen_input
+  LIST(APPEND _doxygen_depend
     ${CMAKE_CURRENT_BINARY_DIR}/tutorial/${_step}.h
     )
 ENDFOREACH()
-TO_STRING(_doxygen_input_string ${_doxygen_input})
-
-file(GLOB _doxygen_image_path
-  ${CMAKE_CURRENT_SOURCE_DIR}/images
-  ${CMAKE_SOURCE_DIR}/examples/*/doc
-  ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/images
-
-  ${CMAKE_CURRENT_BINARY_DIR}/images
-  )
-TO_STRING(_doxygen_image_path_string ${_doxygen_image_path})
 
 FILE(APPEND "${CMAKE_CURRENT_BINARY_DIR}/options.dox"
   "
@@ -139,7 +149,7 @@ ADD_CUSTOM_COMMAND(
     ${CMAKE_CURRENT_BINARY_DIR}/options.dox
     ${CMAKE_CURRENT_BINARY_DIR}/header.html
     ${CMAKE_CURRENT_BINARY_DIR}/footer.html
-    ${_doxygen_input}
+    ${_doxygen_depend}
   COMMENT "Generating documentation via doxygen."
   VERBATIM
   )

doc/doxygen/options.dox.in

@@ -25,7 +25,9 @@ CASE_SENSE_NAMES       = YES
 
 
 INLINE_INHERITED_MEMB  = NO
-STRIP_FROM_PATH        = @CMAKE_SOURCE_DIR@ @CMAKE_BINARY_DIR@
+STRIP_FROM_PATH        = @CMAKE_SOURCE_DIR@/include @CMAKE_BINARY_DIR@/include
+STRIP_FROM_INC_PATH    = @CMAKE_SOURCE_DIR@/include @CMAKE_BINARY_DIR@/include
+FULL_PATH_NAMES        = YES
 JAVADOC_AUTOBRIEF      = NO
 INHERIT_DOCS           = YES
 TAB_SIZE               = 8
@@ -56,14 +58,15 @@ SHOW_USED_FILES        = YES
 
 QUIET                  = YES
 WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 WARN_IF_DOC_ERROR      = YES
 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
 
 INPUT                  =
+RECURSIVE              = YES
 EXCLUDE_PATTERNS       = *.templates.h
 EXAMPLE_PATH           = @CMAKE_BINARY_DIR@/doc/doxygen/tutorial \
                          @CMAKE_SOURCE_DIR@/examples/doxygen

doc/news/changes.h

@@ -79,8 +79,8 @@ inconvenience this causes.
   inheritance is gone. For the most part, this should not lead to any
   incompatibilities except in cases where you accessed members of
   DataOutBase through their derived classes. For example, it was possible
-  to write <code>DataOut@<2@>::Patch@<2,2@></code> even though the
-  <code>Patch</code> class is actually declared in DataOutBase. Since
+  to write DataOut::Patch even though the
+  Patch class is actually declared in DataOutBase. Since
   the inheritance is now gone, this is no longer possible and one
   actually has to write DataOutBase::Patch instead. Using this form
   turns out to be compatible also with older versions of deal.II.

include/deal.II/algorithms/theta_timestepping.h

@@ -180,7 +180,7 @@ namespace Algorithms
    * for us). Here, we first get the time step size from the AnyData
    * object that was provided as input. Then, if we are in the first
    * step or if the timestep has changed, we fill the local matrix
-   * <tt>m</tt>, such that with the given matrix \f$M\f$, it becomes
+   * $m$, such that with the given matrix $M$, it becomes
    * \f[
    * m = I - \Delta t M.
    * \f]
@@ -219,11 +219,11 @@ namespace Algorithms
     /**
      * The timestepping scheme.
      *
-     * @param `in` is ignored by
+     * @param in is ignored by
      * ThetaTimestepping, but is merged into the AnyData objects used
      * as input for the operators #op_explicit and #op_implicit.
      *
-     * @param `out` in its first argument must contain a pointer to a
+     * @param out in its first argument must contain a pointer to a
      * `VECTOR`, which contains the initial value when the operator is
      * called. It contains the final value when the operator returns.
      */
@@ -334,10 +334,10 @@ namespace Algorithms
      * with name "Current time solution". It should obtain the current
      * time and time step size from explicit_data().
      *
-     * Its return value is <i>Mu+cF(u)</i>, where <i>u</i> is the
-     * current state vector, <i>M</i> the mass matrix, <i>F</i> the
-     * operator in space and <i>c</i> is the adjusted
-     * time step size \f$ (1-\theta) \Delta t\f$.
+     * Its return value is $ Mu+cF(u) $, where $u$ is the
+     * current state vector, $M$ the mass matrix, $F$ the
+     * operator in space and $c$ is the adjusted
+     * time step size $(1-\theta) \Delta t$.
      */
     SmartPointer<Operator<VECTOR>, ThetaTimestepping<VECTOR> > op_explicit;
 

include/deal.II/fe/fe_tools.h

@@ -707,15 +707,15 @@ namespace FETools
    * other:
    *
    * - It interpolates directly from every cell of @p dof1 to the
-   *   corresponding cell of @dof2 using the interpolation matrix of the
+   *   corresponding cell of `dof2` using the interpolation matrix of the
    *   finite element spaces used on these cells and provided by
    *   the finite element objects involved. This step is done using the
    *   FETools::interpolate() function.
-   * - It then performs a loop over all non-active cells of @dof2. If
+   * - It then performs a loop over all non-active cells of `dof2`. If
    *   such a non-active cell has at least one active child, then we
    *   call the children of this cell a "patch". We then interpolate
    *   from the children of this patch to the patch, using the finite
-   *   element space associated with @p dof2 and immediately interpolate
+   *   element space associated with `dof2` and immediately interpolate
    *   back to the children. In essence, this information throws away
    *   all information in the solution vector that lives on a scale
    *   smaller than the patch cell.

include/deal.II/grid/filtered_iterator.h

@@ -357,7 +357,7 @@ namespace IteratorFilters
  * @endcode
  * Note that by the @p set_to_next_positive call the first cell with
  * a set user flag was assigned to the @p begin iterator. For the
- * #end iterator, no such call was necessary, since the past-the-end
+ * end iterator, no such call was necessary, since the past-the-end
  * iterator always satisfies all predicates.
  *
  * The same can be achieved by the following snippet, though harder to read:

include/deal.II/grid/grid_generator.h

@@ -57,7 +57,7 @@ namespace GridGenerator
    * Initialize the given triangulation with a hypercube (line in 1D,
    * square in 2D, etc) consisting of exactly one cell. The hypercube
    * volume is the tensor product interval
-   * \f$ [left,right]^{\text{dim}}\f$ in the present number of
+   * $[left,right]^{\text{dim}}$ in the present number of
    * dimensions, where the limits are given as arguments. They default
    * to zero and unity, then producing the unit hypercube. If the
    * argument `colorize` is false, all boundary indicators are set to

include/deal.II/grid/tria_iterator.h

@@ -464,7 +464,7 @@ class TriaRawIterator : public std::iterator<std::bidirectional_iterator_tag,Acc
    * <li> The index of a cell inside the level.</li>
    * </ol>
    *
-   * @Note: the ordering is not consistent between different processor in
+   * @note The ordering is not consistent between different processor in
    * a parallel::distributed::Triangulation because we rely on index(),
    * which is likely not the same.
    */

include/deal.II/lac/trilinos_vector_base.h

@@ -794,7 +794,7 @@ namespace TrilinosWrappers
 
     /**
      *  Output of vector in user-defined format in analogy to the
-     *  dealii::Vector<number> class.
+     *  dealii::Vector class.
      */
     void print (const char *format = 0) const;
 

include/deal.II/meshworker/loop.h

@@ -156,10 +156,6 @@ namespace MeshWorker
    * @param cell_worker defines the local action on each cell.
    * @param boundary_worker defines the local action on boundary faces
    * @param face_worker defines the local action on interior faces.
-   * @param cells_first determines, whether, on a given cell, face or cell
-   *        integrals are to be  dealt with first. Note that independent of the
-   *        value of this flag, cell and face integrals of a given cell are
-   *        all taken care of before moving to the next cell.
    * @param loop_control control structure to specify what actions should be performed.
    *
    * @ingroup MeshWorker

include/deal.II/numerics/data_out.h

@@ -148,7 +148,7 @@ namespace internal
  * this pair of functions and they return a non-active cell, then an exception
  * will be thrown.
  *
- * @precondition This class only makes sense if the first template
+ * @pre This class only makes sense if the first template
  * argument, <code>dim</code> equals the dimension of the
  * DoFHandler type given as the second template argument, i.e., if
  * <code>dim == DH::dimension</code>. This redundancy is a historical

include/deal.II/numerics/data_out_faces.h

@@ -108,7 +108,7 @@ namespace internal
  * applications certainly exist, for which the author is not
  * imaginative enough.
  *
- * @precondition This class only makes sense if the first template
+ * @pre This class only makes sense if the first template
  * argument, <code>dim</code> equals the dimension of the
  * DoFHandler type given as the second template argument, i.e., if
  * <code>dim == DH::dimension</code>. This redundancy is a historical

include/deal.II/numerics/data_out_rotation.h

@@ -114,7 +114,7 @@ namespace internal
  * It is in the responsibility of the user to make sure that the
  * radial variable attains only non-negative values.
  *
- * @precondition This class only makes sense if the first template
+ * @pre This class only makes sense if the first template
  * argument, <code>dim</code> equals the dimension of the
  * DoFHandler type given as the second template argument, i.e., if
  * <code>dim == DH::dimension</code>. This redundancy is a historical