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;