# documer

**Repository Path**: kzhuo/documer

## Basic Information

- **Project Name**: documer
- **Description**: 使用高度自动化的工具，实现懒人的文档自动更新
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2015-07-03
- **Last Updated**: 2023-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#documer

#概述

##背景

您是否处在一个传统行业，如军工、航空航天、铁路、汽车等工控领域？需要复杂的文档作业？

您的行业是否存在第三方强制认证？

您的项目/产品是否需要严格按照强制认证的安全/质量要求进行开发？

您的项目/产品是否具有大量的文档更新和维护工作？

您具有丰富设计和开发经验的工程师是否花费大量的精力维护设计文档？他们拿着架构师的薪水，却干着文档追溯和更新的活?

您的项目成员在代码走查时是否缺乏有效的代码-》图形转换工具？

您是否需要对所购买的第三方库进行快速的结构分析和验证？

您是否一个product manager，发现内容的追溯关系是一团乱麻？

或许您可以试试documer! documer的高效率将给您的开发团队带来新气象！

使用documer，可以有效减轻工作负担，提高文件复用效率，把有经验的工程师从文档工作中解放出来。documer可以：

 - 自动形成详细设计
 - 可替换的文档模板
 - 支持自定义的关键字列表
 - 支持扩充的doxygen关键词
 - 支持文件通配符
 - 支持强制覆盖深度 (force-depth)
 - 支持用于绘制流程图
 - 支持将语法结构导出为xml或其他形式的文件
 - 支持读入xml文件画图
 - 时刻保持更新的、有效的文档

documer首先是一个C语言的语法解析器,通过对词法和语法的分析,解析源程序的控制结构,支持绘制流程图。

documer对源程序控制结构的解析以代码段为基本单位,此处代码段是指能构成独立控制结构的最小单元,

如函数定义,函数调用,赋值语句, if/ese, case分支等。

documer解析来自C语言源文件中的注释,解析函数头部和函数结构,自动绘制visio流程图,并解析生成word文件。

##基本使用

documer目前使用/\*\* \*/风格的doxygen注释和/\*- \*/来提取相关的信息，推荐在函数头部使用doxygen风格，在函数体中使用/\*- \*/，以便和doxygen达到更好地可兼容性。其解析单元为一个代码段,
如果在解析某个代码段过程中找到了相应的注释,则使用注释进行标记,否则使用语句代码进行标记。代码段的标记用于进行流程图的绘制。

代码段的注释中,/\*\* \*/和/\*- \*/注释默认将用于下一行,/\*\*< \*/和/\*-< \*/默认将注释用于当前行。

	/*- 执行动作 */
	do_sth(a, b);

	do_sth(a, b); /*-< 执行动作 */

以上两段代码在解释过程中都将使用"执行动作"标记do_sth(a,b)这个函数调用,在后续绘图过程中解析到do_sth语句时,将使用"执行动作"。


doxygen的注释中还支持@作为关键字的前缀字符。典型的函数头部注释包括：

	@brief 为函数的概述
	@param 为函数的参数
	@return 为函数的返回值
	@depth 为函数的深度
	@alias 可以强制将某个组合语句合并为一个节点
	@details 可以补充详细说明
	@ignore 将跳过本文件的详细设计

documer支持标准的C语言关键字,同时做了以下约定：
 - 所有以_t/_T作为结尾的标识将被认为是int类型,如uint8_t, MYTYPE_T
 - far/FAR将被忽略
 - 函数的@brief描述中,第一个和函数名一样的单词将被忽略
 - 函数头部无描述时,将使用默认的详细设计描述文字
 - 在代码块的注释中,可以使用@alias来强制将代码块处理成一个P节点
 - FOR语句的注释中,可以使用|进行额外的注释

本工具生成的典型详细设计的效果如下：

![Alt text](/_static/fun_header.png "函数详细设计示意")

for循环的注释语句中,使用';'符号可用于分隔初始化语句,条件判断语句,和迭代语句的注释。  ::

    /*- 索引置0 ; 是否尾部? ; 索引递增 */
    for (i=0; i<15; i++)
    {
        do_sth();
    }

以上for循环的流程图如下

![Alt text](/_static/for_flow.png "for语句示意图")

详细设计中的函数原型、函数引用等均为工具自动生成。


##效果示意

动态使用本工具自动生成详细设计文档的步骤示意图如下：

![Alt text](/_static/demo.gif "documer效果示意图")