linux注释风格

linux 注释
===================
  参考文件：kernel/Documentation/kernel-doc-nano-HOWTO.txt
  备注：本文主要从参考文件翻译而来，对内容进行了理解，故算不上翻译。

如何进行linux内核注释
--------------------
  linux kernel不同于linux各个发行版，通常我们所说的linux系统都是指的以linux kernel为
  内核的操作系统。不管各个发行版是什么样的特性，其所使用的内核都是kernel。kernel是一个很
  神奇很大的软件，它有自己的代码风格(缩进，命名，注释，文档...)
  在参考文件中描述了linux的注释风格。主要就是函数体注释，结构体注释。
  函数体注释形如下所示
  /**
   * foobar() - 简短的对函数foobar的描述
   * @arg1:  描述第一个参数
   * @arg2:  描述第二个参数
   *  每一个都可以是多行的描述
   * @argn：  描述第n个参数
   * 
   * 从一个空行开始，然后开始更多的关于函数foobar的描述
   * 可以有多行
   *
   * 可以有多个段
   */


  结构体注释如下
   /**
    * struct blah - 简短的描述这个结构体
    * @mem1: 描述第一个成员
    * @mem2: 描述第二个成员
    *        可以多行
    * 
    * 还是以空行开始进行更多的描述
    * 多行
    *
    * 多个段
    */ 

提取内核注释
------------
  所说的进行如上注释方法，前提是你希望融入内核的注释风格。如果觉得无所谓也无关紧要，毕竟
  自己不写内核，仅仅是驱动函数，但不管怎样，统一注释风格似乎是好事情。
  除了融入内核的注释风格以外，还有一个好处就是，可以利用内核提供的工具，生成注释文档，
  这些注释文档生成的规则就是提取形如上所示的注释风格的注释。参考文档里面有详细的说明。
  在kernel目录下输入如下命令可以生成内核的说明文档
  make psdocs ;#生成对应格式的docs
  make pdfdocs;
  make htmldocs;
  make sgmeldocs;
  不过在此之后，可能不会成功，它会提示安装：  docbook-utils or xmlto
  安装之后就可以生成了
  另外在参考文档中还提供了生成man pages的方法 
  在内核目录新建脚本 split-man.pl,内容如下
  #!/usr/bin/perl

  if ($#ARGV < 0) {
   die "where do I put the results?\n";
  }

  mkdir $ARGV[0],0777;
  $state = 0;
  while (<STDIN>) {
    if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
if ($state == 1) { close OUT }
$state = 1;
$fn = "$ARGV[0]/$1.9";
print STDERR "Creating $fn\n";
open OUT, ">$fn" or die "can't open $fn: $!\n";
print OUT $_;
    } elsif ($state != 0) {
print OUT $_;
    }
  }

  close OUT;
  然后执行如下命令
  chmod +x spit-man.pl;
  scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man;
  scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man;