diff options
Diffstat (limited to 'doc/doxygen/doxygen-input-filter.in')
-rw-r--r-- | doc/doxygen/doxygen-input-filter.in | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/doxygen/doxygen-input-filter.in b/doc/doxygen/doxygen-input-filter.in new file mode 100644 index 0000000..015559a --- /dev/null +++ b/doc/doxygen/doxygen-input-filter.in @@ -0,0 +1,60 @@ +#!@PERL@ -w +# +# Copyright (C) 2006, 2007 Internet Systems Consortium, Inc. ("ISC") +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +# PERFORMANCE OF THIS SOFTWARE. + +# $Id: doxygen-input-filter.in,v 1.4 2007/06/19 23:47:13 tbox Exp $ + +# Input filter for feeding our source code into Doxygen. + +# Slurp whole file at once +undef $/; +$_ = <>; + +# It turns out that there are a lot of cases where we'd really like to +# use what Doxygen calls "brief" documentation in a comment. Doxygen +# has a shorthand way of doing this -- if one is writing C++. ISC +# coding conventions require C, not C++, so we have to do it the +# verbose way, which makes a lot of comments too long to fit on a +# single line without violating another ISC coding standard (80 +# character line limit). +# +# So we use Doxygen's input filter mechanism to define our own +# brief comment convention: +# +# /*% foo */ +# +# expands to +# +# /*! \brief foo */ +# +# and +# +# /*%< foo */ +# +# expands to +# +# /*!< \brief foo */ +# +s{/\*%(<?)}{/*!$1 \\brief }g; + +# Doxygen appears to strip trailing newlines when reading files +# directly but not when reading from an input filter. Go figure. +# Future versions of Doxygen might change this, be warned. +# +s{\n+\z}{}; + +# Done, send the result to Doxygen. +# +print; |