5.2 为代码编写文档
在编程(www.cppentry.com)环境下，文档通常指源文件中的注释。当编写相关代码的时候，注释用来说明您当时的想法。在这里给出的信息很难通过阅读代码获取。
5.2.1 使用注释的原因（1）
很明显使用注释是一个好主意，但是您想过为什么代码需要注释么？有时候程序员意识到注释的重要性，但是没有完全理解为什么注释如此重要。本章将解释使用注释的全部原因。
1. 说明用途的注释
使用注释的原因之一是说明客户如何与代码交互。头文件中每个公有访问的函数或者方法都应该带有解释其行为的注释。某些组织喜欢将注释正式化，明确列出每有方法的目的、方法的参数、方法的返回值以及可能抛出的异常。
为公有方法提供注释完成了两件事情。首先，注释让您获得了一个机会，可以用英语陈述在代码中无法陈述的内容。例如，在C++(www.cppentry.com)中确实没有办法说明数据库对象的saveRecord()方法只能在openDatabase()方法之后调用。但可以使用注释提示这一限制，如下所示：
- /*
- * saveRecord()
- *
- * Saves the given record to the database.
- *
- * This method will throw a "DatabaseNotOpenedException"
- * if the openDatabase() method was not called first.
- */
公有方法注释的第二个效果是可以说明用法。C++(www.cppentry.com)语言强迫您指定方法的返回类型，但是您无法说明返回值实际代表了什么。例如，saveRecord()方法的声明可能指出这个方法返回一个int，但是阅读这个声明的客户无法得知int的含义。在注释中可以加入其他辅助数据，如下所示： - /*
- * saveRecord()
- *
- * Saves the given record to the database.
- *
- * Parameters:
- * Record& rec: the record to save to the database.
- * Returns: int
- * An integer representing the ID of the saved record.
- * Throws:
- * DatabaseNotOpenedException if the openDatabase() method was not
- * called first.
- */
有时函数的参数以及返回值是泛型，可以用来传递任何类型的信息。在此情况下应该清楚地用文档说明所传递的确切类型。例如，Windows的消息处理程序接受两个参数，LPARAM以及WPARAM，返回一个LRESULT。这些参数以及返回值可以传递您喜欢的任何内容，但是您不能改变它们的类型。通过使用类型转换，可以用它们传递简单的整数，或者传递指向某个对象的指针。文档应该是这样的：- * Parameters:
- * WPARAM wParam: (WPARAM)(int): An integer representing an ID.
- * LPARAM lParam: (LPARAM)(string*): A string representing...
- * Returns: (LRESULT)(Record*)
- * A pointer to a Record object or nullptr in case of an error.
大多数编辑器允许绑定按键以执行某种操作。您可以绑定某个按键，从而使得编辑器自动插入一个标准注释块，然后您可以在其中填入正确的信息。例如，可以自动插入下面的注释模板。- /*
- * func()
- *
- * Description of the function.
- *
- * Parameters:
- * int param1: parameter 1.
- * Returns: int
- * An integer representing...
- * Throws:
- * Exception1 if...
- * Notes:
- * Additional notes...
- */