Doxygen filter changes * allow doxygen to process applications/**.H * use @cond/@endcond to suppress documenting classes/variables in applications/

- allows some access from applications to libraries
 - connection between application and local includes is still a bit weak,
   but is possible via the dirs.html navigation.

bin/doxyFilt

@@ -29,9 +29,12 @@
 # Description
 #     pass-through filter for doxygen
 #
-#     Filter has special treatment for applications/{solvers,utilities}/*.C
+#     Special treatment for applications/{solvers,utilities}/*.C
-#       - only keep the first comment block of the C source file
+#     - only keep the first comment block of the C source file
-#       - the corresponding H files are ignored in Doxyfile EXCLUDE_PATTERNS
+#       use @cond / @endcond to suppress documenting all classes/variables
+#
+#     Special treatment for applications/{solvers,utilities}/*.H
+#     - use @cond / @endcond to suppress documenting all classes/variables
 #------------------------------------------------------------------------------
 
 if [ "$#" -gt 0 ]
@@ -41,16 +44,19 @@ then
    dirName=${filePath%/[^/]*}
    fileName=${filePath##*/}
 
-   awkScript=$WM_PROJECT_DIR/bin/doxyAwk
+   awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilt.awk
 
    case "$1" in
    */applications/solvers/*.C | */applications/utilities/*.C )
-      awkScript=$WM_PROJECT_DIR/bin/doxyAwkTop
+      awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilt-top.awk
+      ;;
+   */applications/solvers/*.H | */applications/utilities/*.H )
+      awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilt-ignore.awk
       ;;
    esac
 
    awk -f $awkScript $1 | \
-   sed -f $WM_PROJECT_DIR/bin/doxyScr \
+   sed -f $WM_PROJECT_DIR/bin/tools/doxyFilt.sed \
        -e s@%filePath%@$filePath@g \
        -e s@%fileName%@$fileName@g \
        -e s@%dirName%@$dirName@g

bin/tools/doxyFilt-ignore.awk

@@ -4,7 +4,7 @@
 #  \\    /   O peration     |
 #   \\  /    A nd           | Copyright (C) 1991-2007 OpenCFD Ltd.
 #    \\/     M anipulation  |
-# ------------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 # License
 #     This file is part of OpenFOAM.
 #
@@ -23,41 +23,23 @@
 #     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 #
 # Script
-#     doxyAwkTop
+#     doxyFilt-ignore.awk
 #
 # Description
-#     Output only the first /* ... */ comment section found in the file
+#     - Prefix file contents with doxygen @file tag and %filePath% tag
-#       - This is useful for application files in which only the first
+#       that will be changed in a subsequent sed script
-#         block documents the application itself and all other files simply
+#     - Surround the contents of an entire file with @cond / @endcond
-#         pollute our documentation
+#       to skip documenting all classes/variables
 #
 # -----------------------------------------------------------------------------
 BEGIN {
-    state = 0
+   print "//! @file %filePath%"
+   print "//! @cond OpenFOAMIgnoreAppDoxygen"
 }
 
-# a '/*' at the beginning of a line starts a block
+{ print }
-/^ *\/\*/ {
-    state++
-}
         
-# a '*/' ends the block
+END {
-/\*\// {
+   print "//! @endcond OpenFOAMIgnoreAppDoxygen"
-    if (state == 1)
-    {
-        print
-    }
-    state = 2
-    next
 }
-
-# end block
-{
-    if (state == 1)
-    {
-        print
-    }
-    next
-}
-
 # -----------------------------------------------------------------------------

bin/tools/doxyFilt-top.awk

@@ -0,0 +1,82 @@
+# -----------------------------------------------------------------------------
+# =========                 |
+# \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+#  \\    /   O peration     |
+#   \\  /    A nd           | Copyright (C) 1991-2007 OpenCFD Ltd.
+#    \\/     M anipulation  |
+#------------------------------------------------------------------------------
+# License
+#     This file is part of OpenFOAM.
+#
+#     OpenFOAM is free software; you can redistribute it and/or modify it
+#     under the terms of the GNU General Public License as published by the
+#     Free Software Foundation; either version 2 of the License, or (at your
+#     option) any later version.
+#
+#     OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+#     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+#     for more details.
+#
+#     You should have received a copy of the GNU General Public License
+#     along with OpenFOAM; if not, write to the Free Software Foundation,
+#     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+#
+# Script
+#     doxyFilt-top.awk
+#
+# Description
+#     Only output the first /* ... */ comment section found in the file
+#     Use @cond / @endcond to suppress documenting all classes/variables
+#     - This is useful for application files in which only the first
+#       block documents the application itself.
+#
+# -----------------------------------------------------------------------------
+BEGIN {
+    state = 0
+}
+
+# a '/*' at the beginning of a line starts a comment block
+/^ *\/\*/ {
+   state++
+}
+
+# check first line
+# either started with a comment or skip documentation for the whole file
+FNR == 1 {
+   if (!state)
+   {
+      print "//! @cond OpenFOAMIgnoreAppDoxygen"
+      state = 2
+   }
+}
+
+# a '*/' ends the comment block
+# skip documentation for rest of the file
+/\*\// {
+    if (state == 1)
+    {
+        print
+        print "//! @cond OpenFOAMIgnoreAppDoxygen"
+    }
+    state = 2
+    next
+}
+
+# print everything within the first comment block
+{
+    if (state)
+    {
+        print
+    }
+    next
+}
+
+END {
+    if (state == 2)
+    {
+        print "//! @endcond OpenFOAMIgnoreAppDoxygen"
+    }
+}
+
+# -----------------------------------------------------------------------------

bin/tools/doxyFilt.awk

@@ -4,7 +4,7 @@
 #  \\    /   O peration     |
 #   \\  /    A nd           | Copyright (C) 1991-2007 OpenCFD Ltd.
 #    \\/     M anipulation  |
-# ------------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 # License
 #     This file is part of OpenFOAM.
 #
@@ -23,23 +23,23 @@
 #     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 #
 # Script
-#     doxyAwk
+#     doxyFilt.awk
 #
 # Description
 #     Converts cocoon style sentinel strings into doxygen style strings
 #
-#     - assume the comment strings are formatted as follows
+#     Assumes comment strings are formatted as follows
-#           //- general description
+#         //- general description
-#           //  more information
+#         //  more information
-#           //  and even more information
+#         //  and even more information
-#       This should be re-formatted as the following
+#     This should be re-formatted as the following
-#           //! general description
+#         //! general description
-#           /*!
+#         /*!
-#           more information
+#         more information
-#           and even more information
+#         and even more information
-#           */
+#         */
-#       The intermediate "/*! ... */" block is left-justified to handle
+#     The intermediate "/*! ... */" block is left-justified to handle
-#       possible verbatim text
+#     possible verbatim text
 # -----------------------------------------------------------------------------
 
 BEGIN {
@@ -55,14 +55,14 @@ BEGIN {
 
 
 /^ *\/\// {
-    # start block
+    # start comment block
     if (state == 1)
     {
         printf "/*!\n"
         state = 2
     }
 
-    # inside block
+    # inside comment block
     if (state == 2)
     {
         if (!sub(/^ *\/\/  /, ""))
@@ -77,7 +77,7 @@ BEGIN {
 
 
 {
-    # end block
+    # end comment block
     if (state == 2)
     {
         printf "*/\n"

bin/tools/doxyFilt.sed

@@ -1,3 +1,12 @@
+# -----------------------------------------------------------------------------
+# Script
+#     doxyFilt.sed
+#
+# Description
+#     Transform human-readable tags such as 'Description' into the Doxygen
+#     equivalent
+# -----------------------------------------------------------------------------
+
 /^License/,/\*\//{
 /^License/,/MA 0211.-130. USA/{
 s?^License.*?\*\/\
@@ -141,3 +150,5 @@ s? *\([a-zA-Z0-9]*\.[a-zA-Z]*\)?  <li><a href="%dirName%/\1">\1</a></li>?
 s/.*\*\//\*\//
 
 }
+
+# -----------------------------------------------------------------------------

doc/Doxygen/Doxyfile

@@ -522,9 +522,7 @@ EXCLUDE_SYMLINKS       = NO
 # for example use the pattern */test/*
 
 EXCLUDE_PATTERNS       = */lnInclude/*  \
-                         */t/* \
+                         */t/*
-                         */applications/utilities/*.H \
-                         */applications/solvers/*.H
 
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names