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-2008 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     # wpa_supplicant -> %wpa_supplicant except for struct wpa_supplicant
  74     $t =~ s/struct wpa_supplicant/struct STRUCTwpa_supplicant/sg;
  75     $t =~ s/ wpa_supplicant/ \%wpa_supplicant/sg;
  76     $t =~ s/struct STRUCTwpa_supplicant/struct wpa_supplicant/sg;
  77
  78     # " * func: foo" --> "\brief foo\n"
  79     # " * struct bar: foo" --> "\brief foo\n"
  80     # If this fails, not a kernel-doc comment ==> return unmodified.
  81     ($t =~ s/^[\t ]*\*[\t ]*(struct )?([^ \t\n]*) - ([^\n]*)/\\brief $3\n/s)
  82       or return $t;
  83
  84     # " * Returns: foo" --> "\return foo"
  85     $t =~ s/\n[\t ]*\*[\t ]*Returns:/\n\\return/sig;
  86
  87     # " * @foo: bar" --> "\param foo bar"
  88     # Handle two common typos: No ":", or "," instead of ":".
  89     $t =~ s/\n[\t ]*\*[\t ]*\@([^ :,]*)[:,]?[\t ]*/\n\\param $1 /sg;
  90
  91     return $t;
  92 }
  93
  94 ##########################################################################
  95 # Start of main code
  96
  97 # Read entire stdin into memory - one multi-line string.
  98 $_ = do { local $/; <> };
  99
 100 s{^/\*\n \*}{/\*\* \\file\n\\brief};
 101 s{ \* Copyright}{\\par Copyright\nCopyright};
 102
 103 # Fix any comments like "/*************" so they don't match.
 104 # "/***" ===> "/* *"
 105 s{/\*\*\*}{/\* \*}gs;
 106
 107 # The main comment-detection code.
 108 s{
 109     (               # $1 = Open comment
 110         /\*\*       # Open comment
 111         (?!\*)      # Do not match /*** (redundant due to fixup above).
 112         [\t ]*\n?   # If 1st line is whitespace, match the lot (including the newline).
 113     )
 114     (.*?)           # $2 = Body of comment (multi-line)
 115     (               # $3 = Close comment
 116         (           # If possible, match the whitespace before the close-comment
 117             (?<=\n) # This part only matches after a newline
 118             [\t ]*  # Eat whitespace
 119         )?
 120         \*/         # Close comment
 121     )
 122  }
 123  {
 124     $1 . fixcomment($2) . $3
 125  }gesx;
 126 # ^^^^ Modes: g - Global, match all occurances.
 127 #             e - Evaluate the replacement as an expression.
 128 #             s - Single-line - allows the pattern to match across newlines.
 129 #             x - eXtended pattern, ignore embedded whitespace
 130 #                 and allow comments.
 131
 132 # Write results to stdout
 133 print $_;
 134