Debian Codegraph @

doc/doxygen/doxygen-input-filter.in

raw
1 #!@PERL@ -w
2 #
3 # Copyright (C) Internet Systems Consortium, Inc. ("ISC")
4 #
5 # SPDX-License-Identifier: MPL-2.0
6 #
7 # This Source Code Form is subject to the terms of the Mozilla Public
8 # License, v. 2.0. If a copy of the MPL was not distributed with this
9 # file, you can obtain one at https://mozilla.org/MPL/2.0/.
10 #
11 # See the COPYRIGHT file distributed with this work for additional
12 # information regarding copyright ownership.
13
14 # Input filter for feeding our source code into Doxygen.
15
16 # Slurp whole file at once
17 undef $/;
18 $_ = <>;
19
20 # It turns out that there are a lot of cases where we'd really like to
21 # use what Doxygen calls "brief" documentation in a comment. Doxygen
22 # has a shorthand way of doing this -- if one is writing C++. ISC
23 # coding conventions require C, not C++, so we have to do it the
24 # verbose way, which makes a lot of comments too long to fit on a
25 # single line without violating another ISC coding standard (80
26 # character line limit).
27 #
28 # So we use Doxygen's input filter mechanism to define our own
29 # brief comment convention:
30 #
31 # /*% foo */
32 #
33 # expands to
34 #
35 # /*! \brief foo */
36 #
37 # and
38 #
39 # /*%< foo */
40 #
41 # expands to
42 #
43 # /*!< \brief foo */
44 #
45 s{/\*%(<?)}{/*!$1 \\brief }g;
46
47 # Doxygen appears to strip trailing newlines when reading files
48 # directly but not when reading from an input filter. Go figure.
49 # Future versions of Doxygen might change this, be warned.
50 #
51 s{\n+\z}{};
52
53 # Done, send the result to Doxygen.
54 #
55 print;