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 17undef $/; 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# 45s{/\*%(<?)}{/*!$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# 51s{\n+\z}{}; 52 53# Done, send the result to Doxygen. 54# 55print; 56