The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/Documentation/kernel-doc-nano-HOWTO.txt

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 kernel-doc nano-HOWTO
    2 =====================
    3 
    4 Many places in the source tree have extractable documentation in the
    5 form of block comments above functions.  The components of this system
    6 are:
    7 
    8 - scripts/kernel-doc
    9 
   10   This is a perl script that hunts for the block comments and can mark
   11   them up directly into DocBook, man, text, and HTML. (No, not
   12   texinfo.)
   13 
   14 - Documentation/DocBook/*.tmpl
   15 
   16   These are SGML template files, which are normal SGML files with
   17   special place-holders for where the extracted documentation should
   18   go.
   19 
   20 - scripts/docproc.c
   21 
   22   This is a program for converting SGML template files into SGML
   23   files.  It invokes kernel-doc, giving it the list of functions that
   24   are to be documented.
   25 
   26 - scripts/gen-all-syms
   27 
   28   This is a script that lists the EXPORT_SYMBOL symbols in a list of C
   29   files.
   30 
   31 - scripts/docgen
   32 
   33   This script invokes docproc, telling it which functions are to be
   34   documented (this list comes from gen-all-syms).
   35 
   36 - Makefile
   37 
   38   The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
   39   to build DocBook files, PostScript files, PDF files, and html files
   40   in Documentation/DocBook.
   41 
   42 - Documentation/DocBook/Makefile
   43 
   44   This is where C files are associated with SGML templates.
   45 
   46 
   47 How to extract the documentation
   48 --------------------------------
   49 
   50 If you just want to read the ready-made books on the various
   51 subsystems (see Documentation/DocBook/*.tmpl), just type 'make
   52 psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your 
   53 preference.  If you would rather read a different format, you can type 
   54 'make sgmldocs' and then use DocBook tools to convert 
   55 Documentation/DocBook/*.sgml to a format of your choice (for example, 
   56 'db2html ...' if 'make htmldocs' was not defined).
   57 
   58 If you want to see man pages instead, you can do this:
   59 
   60 $ cd linux
   61 $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
   62 $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
   63 
   64 Here is split-man.pl:
   65 
   66 -->
   67 #!/usr/bin/perl
   68 
   69 if ($#ARGV < 0) {
   70    die "where do I put the results?\n";
   71 }
   72 
   73 mkdir $ARGV[0],0777;
   74 $state = 0;
   75 while (<STDIN>) {
   76     if (/^\.TH \"[^\"]*\" (\d) \"([^\"]*)\"/) {
   77         if ($state == 1) { close OUT }
   78         $state = 1;
   79         $fn = "$ARGV[0]/$2.$1";
   80         print STDERR "Creating $fn\n";
   81         open OUT, ">$fn" or die "can't open $fn: $!\n";
   82         print OUT $_;
   83     } elsif ($state != 0) {
   84         print OUT $_;
   85     }
   86 }
   87 
   88 close OUT;
   89 <--
   90 
   91 If you just want to view the documentation for one function in one
   92 file, you can do this:
   93 
   94 $ scripts/kernel-doc -man -function fn file | nroff -man | less
   95 
   96 or this:
   97 
   98 $ scripts/kernel-doc -text -function fn file
   99 
  100 
  101 How to add extractable documentation to your source files
  102 ---------------------------------------------------------
  103 
  104 The format of the block comment is like this:
  105 
  106 /**
  107  * function_name(:)? (- short description)?
  108 (* @parameterx: (description of parameter x)?)*
  109 (* a blank line)?
  110  * (Description:)? (Description of function)?
  111  * (section header: (section description)? )*
  112 (*)?*/
  113 
  114 The short function description cannot be multiline, but the other
  115 descriptions can be (and they can contain blank lines). Avoid putting a
  116 spurious blank line after the function name, or else the description will
  117 be repeated!
  118 
  119 All descriptive text is further processed, scanning for the following special
  120 patterns, which are highlighted appropriately.
  121 
  122 'funcname()' - function
  123 '$ENVVAR' - environment variable
  124 '&struct_name' - name of a structure (up to two words including 'struct')
  125 '@parameter' - name of a parameter
  126 '%CONST' - name of a constant.
  127 
  128 Take a look around the source tree for examples.
  129 
  130 
  131 How to make new SGML template files
  132 -----------------------------------
  133 
  134 SGML template files (*.tmpl) are like normal SGML files, except that
  135 they can contain escape sequences where extracted documentation should
  136 be inserted.
  137 
  138 !E<filename> is replaced by the documentation, in <filename>, for
  139 functions that are exported using EXPORT_SYMBOL: the function list is
  140 collected from files listed in Documentation/DocBook/Makefile.
  141 
  142 !I<filename> is replaced by the documentation for functions that are
  143 _not_ exported using EXPORT_SYMBOL.
  144 
  145 !F<filename> <function [functions...]> is replaced by the
  146 documentation, in <filename>, for the functions listed.
  147 
  148 
  149 Tim.
  150 */ <twaugh@redhat.com>
  151 

Cache object: fda2630d321587607c8d05792e5e25c4


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.