自动化的API文档设想

似乎作为程序员，每天的工作就是在与代码交互。当然也确实如此，每天都在面对代码，但实际上，真正花在编写代码的时间又占了多少？

我听过一句关于开发的谚语：三分代码 七分文档。然而实际项目中，文档的编辑工作占有率不足百分之10。为什么要拒绝编写文档？

【如何评价一个程序员的能力】

毋庸置疑的一点，能够设计一个完美的架构、编写巧妙的算法、解决复杂问题的程序员是牛逼的程序员，当然也是众人的发展目标。无可厚非。然而大家也似乎忽略了软件管理。我们毫不关心文档的好能够增加自己的同行的地位，反而认为这是一件“文差”。其实也可以想象一下，每天都在写重复的代码的时候，是否想过把他们整理一下，便于交流、共享、重用？

技术经理意识到了这个问题，然而普通人却无法达成共识，以为技术经理有着异样的企图。

显然，在团队中，文化和知识的传承被忽略，软件开发是一项苦逼没有意义的差事，毫无乐趣。这是我们想要的么？

【从API文档开始】

可以先看一看weibo的api接口，不能算得上完美，可以说是及格了。（为什么？有一次我在开发APP的时候，发现调用互粉数量和实际返回的数量不符。开始我认为是我代码的问题，后来发现不是。是微博接口的问题，因为在返回的列表中自动剔除了僵尸用户，而这一切，你并不知道。当然我也是通过给他们反馈问题的时候，他们回复我的，当然这个问题已经被修复了。出问题不可避免，但是在这么大的一个网站中出这样的问题，可以看出在软件管理方面的缺失）。

【自动化的设想】

如果有一天，我不用自己单独打开一个word来编写文档，而是通过我在代码里的注释来实现API文档的自动生成，那么我还会排斥么？

作为一个程序员，我们每天的工作就是编写各种业务来方便用户的使用，那么我们是否想过用同样的方式来将我们自己解放出来？

那么我想的是：

1. 一个符合某种规则的语法 和语法解析器

2. 一个web管理界面

3. 各种输出格式（HTML，PDF，CHM）

4. 最好能够结合SVN、CVS等

流程：我更新完某个代码片段-->然后SVN CO到服务器-->服务器检测到有更新 --> 启动API生成工具 --> 生成API文档 --> 邮件通知相关开发者

这个设想是不是很美好？

那么我需要开始自己设计这个想法了，我要将它实现起来。