文档自动化
— 笔记整理自 北京理工大学 计算机学院
文档自动化
- 文档很重要!
- 软件开发人员不爱写文档
- 软件的使用和维护必需文档
- 多余的文档对客户和开发人员都是一种负担
- 不爱写文档 -> 没人读 -> 文档过时
- 文档自动化的优势
- 简化项目文档生成过程
- 维持精确性、一致性和时效性
- 减轻开发人员负担
设计文档
- 在早期的软件开发过程中，设计和编码是分开的
- 不同的人员使用不同开发工具，程序员编码时很容易偏离设计
- 现在很多IDE厂商如：vs 在其中植入了多工种平台，架构师，设计师，程序员可以在同一个IDE中进行工作
- 从类图到代码，从UML模型到html文档, 再加上版本控制工具，不同工种之间的协作更加流畅了
- Together的代码和类图实现双向同步功能，让文档的编写和生成不再是痛苦的事情
LiveSource TM 技术
- 双向同步功能的建模工具是让人兴奋的事情，之间是单项工具，画好类图后进行生成，比较鸡肋。
- Together的LiveSource TM 技术实现了时时双向同步技术
代码逆向UML图
- 设计阶段的UML图与代码不一致
- 构建时自动生成UML图
- 从本质上来说UML本身也是一种非常重要的文档
- 示例:UMLGraph工具
- UMLGraph和javadoc生成了html格式的UML类图
- 具体做法是：在注解脚本中把代码中想提取的一些javadoc注释的属性传入，生成和代码一致的UML类图
- 这些操作可以封装在脚本里, 自动的跑起来，每次构建都会得到最新的文档并自动发布到开发团队的内部网站上去
数据库文档化
- 绝大多数软件系统都采用数据库来存储数据
- 数据库的设计和管理需要采用很专业的技能
- 数据库设计工具ERWin正向设计流程
- 设计好ER图
- 通过ERWin等工具画出逻辑视图和物理视图
- 确定实体之间的关系
- 确定主键、外键、字段属性等等
- 这些工具可直接连接数据库
- 将物理视图转化为DBL代码, 并在数据库中执行
- 同时可导出各类数据词典文件, 作为数据库设计的文档
- 这些操作很方便，也很强大
- 这里依然存在文档生成的方向性问题
- 程序员在编程过程中需要修改数据库的某个表,字段，如何维持一致性
- 手工维护工作量巨大，不能保证完全的一致性
数据库文档化示例
- 从数据库中抽取所需的元素生成数据库文档
- 这个方案是众多方案中的一个，比较灵活
- 结合SchemaSpy, Ant 和 javadoc 最后生成了html格式的数据库文档
- 配置焦恩可以配置到持续集成的过程中，每次编译后是最新的
备注：图片托管于github，请确保网络的可访问性
代码文档化示例
- 代码的局部说明
- 行注释//…
- 块注释/…/
- Javadoc注释 /** …*/
- Xml注释 ///
- API文档可以更全面了解代码
- 通过Javadoc，Ndoc， Doxgen等文档工具可以将注释和相关代码提取出来，进一步处理为易于阅读的外部文档htm，doc，pdf等
用户文档示例
- 最头疼的是用户文档，大部分时间都浪费在文档的复制粘贴上，对文档的排版更是麻烦
- 结合使用 Ant、一个 DocBook XSL 文件和 XSL Formatting Objects (XSL-FO) 来生成 PDF 格式的用户文档
备注：图片托管于github，请确保网络的可访问性