Commit b92e037e authored by Mark Olesen's avatar Mark Olesen Committed by henry
Browse files

Doxygen filter changes * allow doxygen to process applications/**.H * use...

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.
parent 9ad914ca
......@@ -29,9 +29,12 @@
# Description
# pass-through filter for doxygen
#
# Filter has special treatment for applications/{solvers,utilities}/*.C
# - only keep the first comment block of the C source file
# - the corresponding H files are ignored in Doxyfile EXCLUDE_PATTERNS
# Special treatment for applications/{solvers,utilities}/*.C
# - only keep the first comment block of the C source file
# 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
......
......@@ -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
# - This is useful for application files in which only the first
# block documents the application itself and all other files simply
# pollute our documentation
# - Prefix file contents with doxygen @file tag and %filePath% tag
# that will be changed in a subsequent sed script
# - Surround the contents of an entire file with @cond / @endcond
# to skip documenting all classes/variables
#
# -----------------------------------------------------------------------------
BEGIN {
state = 0
}
# a '/*' at the beginning of a line starts a block
/^ *\/\*/ {
state++
print "//! @file %filePath%"
print "//! @cond OpenFOAMIgnoreAppDoxygen"
}
# a '*/' ends the block
/\*\// {
if (state == 1)
{
print
}
state = 2
next
{ print }
END {
print "//! @endcond OpenFOAMIgnoreAppDoxygen"
}
# end block
{
if (state == 1)
{
print
}
next
}
# -----------------------------------------------------------------------------
# -----------------------------------------------------------------------------
# ========= |
# \\ / 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"
}
}
# -----------------------------------------------------------------------------
......@@ -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
# //- general description
# // more information
# // and even more information
# This should be re-formatted as the following
# //! general description
# /*!
# more information
# and even more information
# */
# The intermediate "/*! ... */" block is left-justified to handle
# possible verbatim text
# Assumes comment strings are formatted as follows
# //- general description
# // more information
# // and even more information
# This should be re-formatted as the following
# //! general description
# /*!
# more information
# and even more information
# */
# The intermediate "/*! ... */" block is left-justified to handle
# 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"
......
# -----------------------------------------------------------------------------
# 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/.*\*\//\*\//
}
# -----------------------------------------------------------------------------
......@@ -522,9 +522,7 @@ EXCLUDE_SYMLINKS = NO
# for example use the pattern */test/*
EXCLUDE_PATTERNS = */lnInclude/* \
*/t/* \
*/applications/utilities/*.H \
*/applications/solvers/*.H
*/t/*
# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment