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.
This commit is contained in:
Mark Olesen
henry
parent
9ad914ca0b
commit
b92e037e52
18
bin/doxyFilt
18
bin/doxyFilt
@ -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
|
||||
print "//! @file %filePath%"
|
||||
print "//! @cond OpenFOAMIgnoreAppDoxygen"
|
||||
}
|
||||
|
||||
# a '/*' at the beginning of a line starts a block
|
||||
/^ *\/\*/ {
|
||||
state++
|
||||
{ print }
|
||||
|
||||
END {
|
||||
print "//! @endcond OpenFOAMIgnoreAppDoxygen"
|
||||
}
|
||||
|
||||
# a '*/' ends the block
|
||||
/\*\// {
|
||||
if (state == 1)
|
||||
{
|
||||
print
|
||||
}
|
||||
state = 2
|
||||
next
|
||||
}
|
||||
|
||||
# end block
|
||||
{
|
||||
if (state == 1)
|
||||
{
|
||||
print
|
||||
}
|
||||
next
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
82
bin/tools/doxyFilt-top.awk
Normal file
82
bin/tools/doxyFilt-top.awk
Normal file
@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
@ -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"
|
||||
@ -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/.*\*\//\*\//
|
||||
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user