文档编写

一个成功的程序库，好的文档是至关重要的！一般需要文档：设计文档，使用指南和参考手册。

文档编制和重用性

没有经过适当文档化的代码不能成为可重用代码，一个设计得很好的程序库，如果文档编制得好，那么将会是一个文档齐全的程序库，否则会功亏一篑，对于希望快速学会如何使用程序库的用户而言，好的文档是必不可少的。就算是小规模的程序库，也不应该忽视文档的编写。衡量一个好的程序库的文档，如果设计和实现相同功能新程序库的时间比学习这个程序库的时间要多得多，这个程序库才是成功的！
编制高质量的文档通常都会占用设计、实现和测试程序很大的一部分时间，之所以需要编制好的文档，主要是由于开发可重用代码的开销要比开发单一用途代码的开销多很多。
每一个可重用的C++程序库都至少应该附带设计文件、使用指南和参考手册。

设计文档

C++程序库的设计文档至少应该回答下列问题：
1、程序库提供了哪些类
2、继承体系如何
3、程序库的所有类是否都是nice类
4、程序库的效率如何
5、在什么条件下，程序库才是可扩展的
6、该程序库是否使用了其他程序库？如果是，那么该程序库已经测试了其他程序库的那些版本？
7、程序库是否具有向前或者向后的源码代码兼容性、链接兼容性、运行兼容性或者进程兼容性？
8、程序库的错误处理机制如何
9、程序的可移植性如何
10、该程序库是否会和其他程序库发生冲突

使用指南

使用指南的用途是在于帮助用户可以学会使用这个程序库，因此它省略了许多关于程序库的高级或者特殊用法方面的细节。提供一个用于整个程序库的使用指南，而且还应该为程序库的每个类或者相关类的集合提供单独的使用指南。
编写使用指南几乎就是一门艺术，学习这种艺术最好的方法就是阅读他人写得好的使用指南，然而仿照写出自己程序库的使用指南。
1、对读者的背景知识了如指掌，注意用语或者说要用通俗化语言
2、用抽象的观点来编写。编写的函数行为应该依据它们对对象抽象值得影响，而不是依据它们的底层实现，应当给出高层解释！
3、先解释普通用法。并不是所有的功能都必须加以解释，更不用不分轻重地解释。指南通常只需要给出让用户知道如何开始操作的知识，和用户经常希望使用的功能等方面的知识。
4、一次只解释一个事物。冗杂太多不利用用户快速上手。
5、只解释用法，不解释设计思路
6、简单清楚地编写
7、准确地使用语言
8、使用普遍接受的术语
9、深刻理解重载的术语
10、给出合法的、无错误的代码。使用指南中的代码不应该存在无意的错误，如果出现语法或者逻辑错误，那只能说明没有对代码例子进行严格的测试。代码编写者是非常粗心和懒惰的，从而也会导致用户对程序库或使用指南失去信心，或者对两者都失去信心。
11、保持简短的代码段。代码例子越长，用户跳过这段代码或者产生疑惑的可能性就越大。如果需要说明观点需要很多行代码，那么应该用代替的文本把这些代码分开！通过文字解释，对代码块进行切割！
12、避免使用太大的函数。如果函数实在是大，那么使用整体和局部另外说明的方式！
13、提供在线实例。

参考手册

大多数C++程序库主要是由类的集合组成的，因此，程序库文档的编写者应该知道如何完整、准确地文档化一个类。总而言子类X的文档应该包含下列几个方面：（Qt的参考手册）
1、告诉用户需要#include哪些文件才能得到类X的定义。除非有充分的理由采用其他方式，否则程序库的每个公共头文件都应该#include或者申明它所需要的对象。采用这种方法后，我们就不会为了得到某个类的定义，而需要#include多个头文件。
2、定义类X的抽象
3、给出类X的语法接口
4、描述X接口中每个函数的语义
5、声明任何对模板参数的限制条件

抽象化
清晰定义每个类的抽象，不管多么过分强调，都是合情合理的。为了可以巧妙地使用某个楼，用户必须先知道这个类所模拟的抽象。

语法接口
类里面函数接口的类型，以及权限，参数，返回值

函数语义
1、语义的解释应该依据给对象的抽象值，而不是对象底层实现
2、当文档化虚函数的时候，还应该指定它的继承语义
3、当返回类型为指针或引用的函数被文档化时，应该指出这个返回值的生存期
4、如果函数抛出异常，还应该指定每个异常的类型和这个异常的抛出条件

模板参数约束
任何对类模板参数或者函数模板参数的约束，都应该在参考手册中进行文档化！对参数的说明！