contrib/wpa/hostapd/doc/kerneldoc2doxygen.pl

   1 #!/usr/bin/perl -w
   2 #
   3 ##########################################################################
   4 # Convert kernel-doc style comments to Doxygen comments.
   5 ##########################################################################
   6 #
   7 # This script reads a C source file from stdin, and writes
   8 # to stdout.  Normal usage:
   9 #
  10 # $ mv file.c file.c.gtkdoc
  11 # $ kerneldoc2doxygen.pl <file.c.gtkdoc >file.c
  12 #
  13 # Or to do the same thing with multiple files:
  14 # $ perl -i.gtkdoc kerneldoc2doxygen.pl *.c *.h
  15 #
  16 # This script may also be suitable for use as a Doxygen input filter,
  17 # but that has not been tested.
  18 #
  19 # Back up your source files before using this script!!
  20 #
  21 ##########################################################################
  22 # Copyright (C) 2003 Jonathan Foster <jon@jon-foster.co.uk>
  23 # Copyright (C) 2005 Jouni Malinen <j@w1.fi>
  24 # (modified for kerneldoc format used in wpa_supplicant)
  25 #
  26 # This program is free software; you can redistribute it and/or modify
  27 # it under the terms of the GNU General Public License version 2 as
  28 # published by the Free Software Foundation.
  29 #
  30 # This program is distributed in the hope that it will be useful,
  31 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  32 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  33 # GNU General Public License for more details.
  34 #
  35 # You should have received a copy of the GNU General Public License
  36 # along with this program; if not, write to the Free Software
  37 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  38 # or look at http://www.gnu.org/licenses/gpl.html
  39 ##########################################################################
  40
  41
  42 ##########################################################################
  43 #
  44 # This function converts a single comment from gtk-doc to Doxygen format.
  45 # The parameter does not include the opening or closing lines
  46 # (i.e. given a comment like this:
  47 #    "/**\n"
  48 #    " * FunctionName:\n"
  49 #    " * @foo: This describes the foo parameter\n"
  50 #    " * @bar: This describes the bar parameter\n"
  51 #    " * @Returns: This describes the return value\n"
  52 #    " *\n"
  53 #    " * This describes the function.\n"
  54 #    " */\n"
  55 # This function gets:
  56 #    " * FunctionName:\n"
  57 #    " * @foo: This describes the foo parameter\n"
  58 #    " * @bar: This describes the bar parameter\n"
  59 #    " * @Returns: This describes the return value\n"
  60 #    " *\n"
  61 #    " * This describes the function.\n"
  62 # And it returns:
  63 #    " * This describes the function.\n"
  64 #    " *\n"
  65 #    " * @param foo This describes the foo parameter\n"
  66 #    " * @param bar This describes the bar parameter\n"
  67 #    " * @return This describes the return value\n"
  68 # )
  69 #
  70 sub fixcomment {
  71     $t = $_[0];
  72
  73     # " * func: foo" --> "\brief foo\n"
  74     # " * struct bar: foo" --> "\brief foo\n"
  75     # If this fails, not a kernel-doc comment ==> return unmodified.
  76     ($t =~ s/^[\t ]*\*[\t ]*(struct )?([^ \t\n]*) - ([^\n]*)/\\brief $3\n/s)
  77       or return $t;
  78
  79     # " * Returns: foo" --> "\return foo"
  80     $t =~ s/\n[\t ]*\*[\t ]*Returns:/\n\\return/sig;
  81
  82     # " * @foo: bar" --> "\param foo bar"
  83     # Handle two common typos: No ":", or "," instead of ":".
  84     $t =~ s/\n[\t ]*\*[\t ]*\@([^ :,]*)[:,]?[\t ]*/\n\\param $1 /sg;
  85
  86     return $t;
  87 }
  88
  89 ##########################################################################
  90 # Start of main code
  91
  92 # Read entire stdin into memory - one multi-line string.
  93 $_ = do { local $/; <> };
  94
  95 s{^/\*\n \*}{/\*\* \\file\n\\brief};
  96 s{ \* Copyright}{\\par Copyright\nCopyright};
  97
  98 # Fix any comments like "/*************" so they don't match.
  99 # "/***" ===> "/* *"
 100 s{/\*\*\*}{/\* \*}gs;
 101
 102 # The main comment-detection code.
 103 s{
 104     (               # $1 = Open comment
 105         /\*\*       # Open comment
 106         (?!\*)      # Do not match /*** (redundant due to fixup above).
 107         [\t ]*\n?   # If 1st line is whitespace, match the lot (including the newline).
 108     )
 109     (.*?)           # $2 = Body of comment (multi-line)
 110     (               # $3 = Close comment
 111         (           # If possible, match the whitespace before the close-comment
 112             (?<=\n) # This part only matches after a newline
 113             [\t ]*  # Eat whitespace
 114         )?
 115         \*/         # Close comment
 116     )
 117  }
 118  {
 119     $1 . fixcomment($2) . $3
 120  }gesx;
 121 # ^^^^ Modes: g - Global, match all occurances.
 122 #             e - Evaluate the replacement as an expression.
 123 #             s - Single-line - allows the pattern to match across newlines.
 124 #             x - eXtended pattern, ignore embedded whitespace
 125 #                 and allow comments.
 126
 127 # Write results to stdout
 128 print $_;
 129