晨光（Morning） DOC++ 注释 DOC++是一种根据注释自动生成文档的工具，它支持C++、Java等多种语言，本文源自DOC++所附之联机文档，欲了解DOC++的详细信息可访问其官方网站 DOC++的思路是为程序员提供一种工具，使其在撰写高质量文档的同时仍能将注意力集中到程序开发上。为了达到这个目的，尤为重要的一点是程序员能够将文档内容添加到其所开发的源码中。只有采用这种方式，程序员才真正愿意为他/她的类、方法等编写文档，并在随后的代码变更中保证其始终是最新的。与此同时，直接编译代码而无需预先过滤处理也是必要的（使用像cweb这样的工具时，就需要过滤处理）。因此，程序中可以放置文档的地方唯有注释。 这正是DOC++用以生成文档的方法。但是，程序员需要区分两种类型的注释。其一是他/她用来帮助记忆某些实现细节的；其二是用来说明类、函数等，以使自己或他人日后可以使用该处代码。在DOC++中，通过不同书写方式来区分这两类注释。与JavaDoc相似，文档注释具有如下格式： /** ... */ /// ... 文档内容写在“...”处。这样的注释被称为DOC++注释，每个DOC++注释为源码中的后续声明产生一条手册条目（manual entry）。在Quantel模式下，尾端注释（trailing comments）也可以被用来产生手册条目。 现在，让我们考虑一下“高质量”的文档意味着什么。 许多程序员喜欢通过简单地单击他们的鼠标按键来查看在线文档。HTML是此类文档的一个标准，几乎每台机器上都能找到出色的HTML浏览器。因此，DOC++被设计成以一种结构化的方式生成HTML格式的输出。 但是，你是否打印过HTML页面？较之人们的以往习惯，其结果是否很不美观？对DOC++而言这并非问题，因为它同时也提供TeX格式的输出，用以生成高质量的硬拷贝（hardcopies）。 对两种输出格式而言，文档结构良好（well structured）很重要。DOC++分别提供了层次结构（hierarchies）功能和HTML页面的层次结构，前者以sections/subsections等形式反映出来。DOC++还会创建一个索引，以方便用户查找。 因为C++和Java或多或少都是面向对象的语言，于是引入了另一种层次结构，类层次结构。阅读此类层次结构的最好方法是图示法。确实如此，DOC++会为每个类继承结构自动生成一幅图，或者在HTML格式的输出中以Java applet方式显示之。 使用DOC++的一个附带好处是，它可以为C和C++代码生成一个TeX typeset源码列表。