Nachos 源码完全注释（序）

陈向群老师的课马上就要结课了，话说我对这个幼儿园级别的OS还基本没怎么看。
听说考试还有个关于nachos的笔试和面试，在网上找了些资料，都没与超出陈老师给的文献，而且关于源码注释分析的更少了。
我想一方面因为这个OS真心不完整，没啥可注释的代码，内容需要我们去添加，另一方面，底层的东西，搞软件的不太懂，用老师的话说，
如果你不想重新编译源码，那就不要动machine这个文件夹里的东西。
嘿嘿，就动！就看！就改！
改完之后就编译不过了。。。

作为嵌入式的DS一枚，我想还是要搞一搞的，虽然现在时间有些紧，各种项目，还在翻译几本书，但是兴趣来了，挡也挡不住，怎么办呢？
干！

我想给源码来个注释，如果顺利完成的话，能给学弟学妹们造福最好，要是能给期末成绩加个分啥的，那就更靠谱了。
话不多说，掳袖子就开干。

可无规矩不成方圆，既然要进行源码注释，就要有个注释的基本规则和要求，乱注释不太好，重用性也低。
最近在做linux内核分析的任务，项目中使用了doxgen这个文档生成神器，所以就用这个了。对源码生成了一遍，加上dox生成图像，结果啥也没有
没办法，只能自己动手了。
基于此，从网上找了一篇关于doxgen的注释规则拉过来，权当进行一次工程化演习吧。

doxygen注释块

doxygen注释块其实就是在C"C++注释块的基础添加一些额外标识, 使doxygen把它识别出来, 并将它组织到生成的文档中去。

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的，但不能同时没有。

顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。

在doxygen中, 有多种方法将注释块标识成详细描述:

1. 你可以使用JavaDoc风格, 即在C风格注释块开始使用两个星号'*', 就像这样:

2. /**

3.  * ... 描述 ...

4.  */

简述同样也可以同种写法:

1. 一种是在一个doxygen注释块中使用 "brief . 这个命令只对当前一个文字段有效, 所以详细描述应该与之间隔一个空行.

像这样:

/*! "brief 这里是简要描述.

 *         这里仍然是简要描述.

 *

 * 详细描述从这里开始.

 */

点击这里查看doxygen产生的HTML文档.

只有一行的注释段包含的是简述, 而多行的注释段则包含的是详细描述.

简要描述可以被用来进行class、namespace或者文件的成员描述, 被以较小的斜体字型显示出来。(这种描述可以通过将BRIEF_MEMBER_DESC设置成NO来隐藏。)默认情况下，简要描述会被显示成详细描述的第一个句子。(这同样可以通过将REPEAT_BRIEF设置成NO来屏蔽。)在Qt风格中, 两种描述都是可选的。

在成员后面放置文档

如果你想对文件、结构体、联合体、类或者枚举的成员进行文档注释的话, 并且要在成员中间添加注释, 而这些注释往往都是在每个成员后面。为此, 你可以使用在注释段中使用'<'标识

Here are some examples:

int var; /*!< Detailed description after the member */

@file	档案的批注说明。
@author	作者的信息
@brief	用于class 或function的简易说明 eg： @brief 本函数负责打印错误信息串
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return	描述该函数的返回值情况 eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval	描述返回值类型 eg: @retval NULL 空字符串。 @retval !NULL 非空字符串。
@note	注解
@attention	注意
@warning	警告信息
@enum	引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg： @enum CTest::MyEnum
@var	引用了某个变量，Doxygen会在该枚举处产生一个链接 eg： @var CTest::m_FileKey
@class	引用某个类， 格式：@class [] [] eg: @class CTest "inc/class.h"
@exception	可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常