| 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; |