CN105094836A - 一种生成说明文档的方法和装置 - Google Patents

Abstract

本发明公开了一种生成说明文档的方法和装置。该方法包括：遍历至少一个组件，查找使用者所需的组件；从预先创建的第一文件中获取使用者所需的组件的使用说明，第一文件独立于保存源码的文件；从预先创建的第二文件中获取使用者所需的组件的示例代码，第二文件独立于保存源码的文件，并且第二文件中的示例代码能够运行；由获取的使用说明和示例代码生成使用者所需的组件的说明文档。通过本发明，减轻了程序开发人员的负担。

Description

一种生成说明文档的方法和装置

技术领域

本发明涉及计算机技术领域，尤其涉及一种生成说明文档的方法和装置。

背景技术

脚本语言是为了缩短传统的编写-编译-链接-运行过程而创建的计算机编程语言。JavaScript是一种应用于Web的脚本语言，已经被广泛用于Web应用开发。浏览器可以在JavaScript下编写源码来实现，不同浏览器的JavaScript源码不同。由于不同浏览器的JavaScript源码不同，所以不同的浏览器难以兼容。JavaScript框架能实现浏览器的兼容。

AngularJS是其中一种JavaScript框架。由于AngularJS当前很热门，所以程序开发人员热衷于基于AngularJS来开发组件。众所周知的是，在基于AngularJS对组件进行开发的过程中，程序开发人员开发的组件需要有相应的说明文档，以向组件的使用者说明所开发的组件如何使用。

当前，生成说明文档的方法依赖于程序开发人员在编写源码过程中所写的注释。该方法主要包括以下几步：获取程序开发人员在编写源码过程中写的注释，对所获取的注释进行解析以将其转换成预定义的格式，生成说明文档。说明文档通常包括使用说明和示例代码，示例代码用于向组件的使用者展示对所开发的组件调用之后的运行结果。

然而，现有的生成说明文档的方法给程序开发人员造成了很大的负担。一方面，由于该方法依赖于注释，所以程序开发人员在编写源码的过程中不得不花大量的精力和时间来写注释，结果写注释成了程序开发人员的负担；另一方面，因为说明文档包含有示例代码并且说明文档的生成依赖于注释，所以示例代码只得包含在注释中，这样所造成的结果是：在对开发的组件进行测试时，由于注释中的内容是不会被运行的，所以包含在注释中的示例代码无法被重复利用，程序开发人员只得重新准备一份测试代码来测试开发的组件。

发明内容

有鉴于此，本发明提供一种生成说明文档的方法和装置，以减轻程序开发人员的负担。

一种生成说明文档的方法，所述方法包括：

遍历至少一个组件，查找使用者所需的组件；

从预先创建的第一文件中获取使用者所需的组件的使用说明，所述第一文件独立于保存源码的文件；

从预先创建的第二文件中获取使用者所需的组件的示例代码，所述第二文件独立于保存源码的文件，并且所述第二文件中的示例代码能够运行；

由获取的所述使用说明和所述示例代码生成使用者所需的组件的说明文档。

优选地，从预先创建的第一文件中获取使用说明包括：

根据grunt的配置信息中预先定义的所述第一文件的文件名称查找所述使用说明；

优选地，从预先创建的第二文件中获取示例代码包括：

根据grunt的配置信息中预先定义的所述第二文件的文件名称查找所述示例代码。

优选地，由获取的使用说明和示例代码生成组件的说明文档包括：

将获取的所述使用说明和所述示例代码写入grunt的配置信息中；

获取所述说明文档的html页面模板；

将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合，从而生成html文档形式的说明文档。

优选地，将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合包括：

将配置信息中的所述使用说明和所述示例代码解析到所述html页面模板中。

优选地，将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合包括：

将配置信息中的所述示例代码解析到所述html页面模板中，并将配置信息中的使用说明保存在所述html页面模板中。

一种生成说明文档的装置，所述装置包括：

第一查找单元，用于遍历至少一个组件，查找使用者所需的组件；

第一获取单元，用于从预先创建的第一文件中获取使用说明，所述第一文件独立于保存源码的文件；

第二获取单元，用于从预先创建的第二文件中获取示例代码，所述第二文件独立于保存源码的文件，并且所述第二文件中的示例代码能够运行；

生成单元，用于由获取的所述使用说明和所述示例代码生成组件的说明文档。

优选地，所述第一获取单元包括：

第二查找单元，用于根据grunt的配置信息中预先定义的所述第一文件的文件名称查找所述使用说明；

优选地，所述第二获取单元包括：

第三查找单元，用于根据grunt的配置信息中预先定义的所述第二文件的文件名称查找所述示例代码。

优选地，所述生成单元包括：

写入单元，用于将获取的所述使用说明和所述示例代码写入grunt的配置信息中；

第三获取单元，用于获取所述说明文档的html页面模板；

结合单元，用于将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合，从而生成html文档形式的说明文档。

优选地，所述结合单元包括：

第一解析单元，用于将配置信息中的所述使用说明和所述示例代码解析到所述html页面模板中。

优选地，所述结合单元包括：

第二解析单元，用于将配置信息中的所述示例代码解析到所述html页面模板中；

保存单元，用于将配置信息中的使用说明保存在所述html页面模板中。

可以看出，由于组件的使用说明和示例代码均以独立于源码的形式保存在各自的文件中，不再包含在源码的注释中，所以程序开发人员在编写源码的过程中无需对注释花费过多精力和时间，并且由于本发明的示例代码可以运行，所以通过本发明，示例代码还可以用于测试组件，故程序开发人员无需准备两份代码分别用于生成说明文档和测试组件，从而极大地减轻了程序开发人员的负担。

附图说明

图1为本发明提供的一种方法的流程图；

图2为本发明实施例最终生成的html页面形式的说明文档的示意图；

图3为本发明实施例组件架构示意图；

图4为本发明实施例提供的一种方法的流程图；

图5为本发明提供的一种装置的框图；

图6为本发明实施例提供的一种装置的框图。

具体实施方式

在对详细的描述进行说明之前，应该理解，用在本说明书以及权利要求中的术语及词语可能不限于普通含义或词典含义，而是在发明人能够使用新词以最佳方式解释本发明的原则下，被解释为适于本发明技术范围的含义或概念。

本发明提供实施例使得公开充分并完全涵盖本领域技术人员。对具体细节例如具体部件、装置进行阐述，以透彻理解本实施例。对本领域技术人员来说，显然，不需要采用具体的细节，实施例可以以许多不同的形式进行具体体现，而且不应该解释为对本发明范围的限制。在一些实施例中，公知装置结构、以及公知技术不再详细描述。

尽管术语第一、第二可以用来描述各种部件，这些部件不应被这些术语限制。这些术语可以仅用来将一个部件与另一部件区别开来。除非上下文清楚地指出，当使用例如“第一”、“第二”、以及其它数字术语这样的术语时，不暗指序列或者顺序。因此，在不背离实施例的原则的情况下，描述的第一部件可以被称为第二部件。

在下文中，将参考附图对本发明的示例性实施例进行详细描述。

本发明提供的方法不依赖于注释，而是将生成说明文档所需的示例代码和使用说明分别独立于源码保存为单独的文件，所以不必迫使程序开发人员在编写源码时以生成组建说明文档为目的而额外地编写大量的注释，并且由于示例代码被可执行地保存在单独的文件中而没有包含在注释中，所以在测试组件时示例代码可以被重复利用，进一步减轻了程序开发人员的负担。

请参考图1，为本发明提供的一种方法的流程图，可以包括以下步骤：

步骤101：遍历至少一个组件，查找使用者所需的组件；

步骤102：从预先创建的第一文件中获取使用者所需的组件的使用说明，第一文件独立于保存源码的文件；

步骤103：从预先创建的第二文件中获取使用者所需的组件的示例代码，第二文件独立于保存源码的文件，并且第二文件中的示例代码能够运行；

步骤104：由获取的使用说明和示例代码生成使用者所需的组件的说明文档。

需要指出的是，上述方法的执行顺序不限于此。例如，步骤102和步骤103的执行顺序可以互换。

可以看出，由于组件的使用说明和示例代码均以独立于源码的形式保存在各自的文件中，不再包含在源码的注释中，所以程序开发人员在编写源码的过程中无需对注释花费过多精力和时间，并且由于本发明的示例代码可以运行，所以通过本发明，示例代码还可以用于测试组件，故程序开发人员无需准备两份代码分别用于生成说明文档和测试组件，从而极大地减轻了程序开发人员的负担。

下面以一个更加详细的实施例介绍本发明。

首先介绍该实施例所需的安装环境。在本实施例中，基于AngularJS来开发组件，所以说明文档的html页面应由AngularJS来驱动；由于通过调用grunt来生成说明文档，所以需要安装grunt；因为grunt运行在nodejs环境下，所以在安装grunt之前还需要安装nodejs。可以理解的，所需的安装环境不限于此。

为了更好地理解本实施例，还需要指出的是，本实施例提供的方法最终将以html页面的形式向组件使用者展示说明文档，可以理解的，向组件使用者展示说明文档的方式不限于此。html页面形式的说明文档包括使用说明、示例代码及其运行结果。请参考图2，为本实施例最终生成的html页面形式的说明文档的示意图。

请参考图3，为本实施例组件架构示意图。根据图3，本实施例可以包括多个(例如三个)组件，其中，组件1可以包括三个部分：源码、示例代码和使用说明，源码包括js源码，可选地，源码还可以包括html源码和css源码，示例代码包括示例js代码和示例html代码。

在生成说明文档之前需要预先创建使用说明和示例代码，本实施例在markdown下创建使用说明。在本实施例中，使用说明保存在第一文件中，例如，第一文件可以包括文件名称为readme.md的一个文件；示例代码保存在第二文件中，例如，第二文件可以包括文件名称分别为demo.html和demo.js的两个文件，这两个文件中的示例代码都是可以运行的；源码保存在第三文件中，例如，第三文件可以包括文件名称为componentA.js的一个文件。

请参考图4，为本实施例提供的一种方法的流程图，可以包括以下步骤：

步骤401：在markdown下创建组件A的使用说明并将其保存在第一文件中；

步骤402：创建组件A的示例代码并将其保存在第二文件中；

需要说明的是，后续步骤通过调用grunt来实现。需要指出的是，grunt的配置信息包括预先定义的组件名称、预先定义的第一文件的文件名称以及预先定义的第二文件的文件名称，grunt的配置信息还包括使用说明和示例代码，与预先定义的组件名称、第一文件的文件名称以及第二文件的文件名称不同的是，grunt的配置信息中的使用说明和示例代码需要在grunt查找到所需的使用说明和示例代码后来写入，如下文所描述的。

步骤403：根据grunt的配置信息中预先定义的组件A的名称查找组件A；

步骤404：根据grunt的配置信息中预先定义的第一文件的文件名称查找组件A的使用说明；

步骤405：根据grunt的配置信息中预先定义的第二文件的文件名称查找组件A的示例代码；

步骤406：将使用说明和示例代码写入grunt的配置信息中；

步骤407：获取说明文档的html页面模板；

步骤408：将配置信息中的使用说明和示例代码解析到html页面模板中，从而生成html文档形式的说明文档；

步骤409：将说明文档输出到grunt的配置目标文件中。

步骤410：以html页面的形式向组件的使用者展示组件A的说明文档。

可以看出，该实施例在生成说明文档时不再从源码的注释中获取使用说明和示例代码，所以程序开发人员不必花费大量的时间和精力来编写注释，而且由于示例代码独立于注释是可以运行的，所以示例代码还可以用来对组件进行测试，故程序开发人员无需准备两份代码来分别用于生成说明文档和对组件进行测试。此外，在该实施例中，使用说明是在markdown下创建的，因为markdown有专门的可视化编辑工具，所以可以可视化创建使用说明，从而便于根据所期望的使用说明的格式随时进行调整。

如本领域技术人员可以理解的，本发明的方法所提供的步骤可以以不同的顺序来执行。例如，在图4中，步骤401和步骤402的执行顺序可以互换。再如，在图4中，步骤404和步骤405的执行顺序也可以互换。

如本领域技术人员可以理解的，对于步骤408，可替换地，将配置信息中的示例代码解析到html页面模板中并将配置信息中的使用说明保存在html页面模板中。此时，对于步骤410，可替换地，对html页面模板中的使用说明进行渲染，并以html页面的形式向组件的使用者展示组件A的说明文档。

请参考图5，为本发明提供的一种装置的框图，可以包括以下单元：

第一查找单元501，用于遍历至少一个组件，查找使用者所需的组件；

第一获取单元502，用于从预先创建的第一文件中获取使用说明，第一文件独立于保存源码的文件；

第二获取单元503，用于从预先创建的第二文件中获取示例代码，第二文件独立于保存源码的文件，并且第二文件中的示例代码能够运行；

生成单元504，用于由获取的使用说明和示例代码生成组件的说明文档。

可以看出，由于组件的使用说明和示例代码均以独立于源码的形式保存在各自的文件中，不再包含在源码的注释中，所以程序开发人员在编写源码的过程中无需对注释花费过多精力和时间，并且由于本发明的示例代码可以运行，所以通过本发明，示例代码还可以用于测试组件，故程序开发人员无需准备两份代码分别用于生成说明文档和测试组件，从而极大地减轻了程序开发人员的负担。

请参考图6，为本发明一个实施例提供的装置的框图，该实施例中所包含的单元如下：

第一获取单元502包括：

第二查找单元601，用于根据grunt的配置信息中预先定义的第一文件的文件名称查找使用说明；

第二获取单元503包括：

第三查找单元602，用于根据grunt的配置信息中预先定义的第二文件的文件名称查找示例代码。

生成单元504包括：

写入单元603，用于将获取的使用说明和示例代码写入grunt的配置信息中；

第三获取单元604，用于获取说明文档的html页面模板；

结合单元605，用于将配置信息中的使用说明和示例代码与html页面模板进行结合，从而生成html文档形式的说明文档。

结合单元605包括：

第一解析单元606，用于将配置信息中的使用说明和示例代码解析到html页面模板中。

可替换地，结合单元605包括：

第二解析单元，用于将配置信息中的示例代码解析到html页面模板中；

保存单元，用于将配置信息中的使用说明保存在html页面模板中。

此处使用的术语仅是为了描述具体的实施例，意不在限制。如此处使用的，除非上下文清楚指出，术语“包括”是包含的，因此详细说明陈述的特征、整体、步骤、操作、元件、和/或部件，并不排除一个或者多个其它的特征、整体、步骤、操作、元件、部件、和/或其组合的存在或附加。

提供本实施例的描述目的是进行说明，意不在穷尽或者限制本发明。单个部件或者特征不限制在该实施例中，即使没有具体示出或者进行描述，也可以在可应用的选择的实施例中进行互换并使用。还可以按照许多方式进行变化，这些变化并未脱离本发明，并且所有这些改变意在包含在本发明的范围内。

Claims (10)

1.一种生成说明文档的方法，其特征在于，所述方法包括：

遍历至少一个组件，查找使用者所需的组件；

从预先创建的第一文件中获取使用者所需的组件的使用说明，所述第一文件独立于保存源码的文件；

从预先创建的第二文件中获取使用者所需的组件的示例代码，所述第二文件独立于保存源码的文件，并且所述第二文件中的示例代码能够运行；

由获取的所述使用说明和所述示例代码生成使用者所需的组件的说明文档。

2.根据权利要求1所述的方法，其特征在于，

从预先创建的第一文件中获取使用说明包括：

根据grunt的配置信息中预先定义的所述第一文件的文件名称查找所述使用说明；

从预先创建的第二文件中获取示例代码包括：

根据grunt的配置信息中预先定义的所述第二文件的文件名称查找所述示例代码。

3.根据权利要求2所述的方法，其特征在于，由获取的使用说明和示例代码生成组件的说明文档包括：

将获取的所述使用说明和所述示例代码写入grunt的配置信息中；

获取所述说明文档的html页面模板；

将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合，从而生成html文档形式的说明文档。

4.根据权利要求3所述的方法，其特征在于，将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合包括：

将配置信息中的所述使用说明和所述示例代码解析到所述html页面模板中。

5.根据权利要求3所述的方法，其特征在于，将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合包括：

将配置信息中的所述示例代码解析到所述html页面模板中，并将配置信息中的使用说明保存在所述html页面模板中。

6.一种生成说明文档的装置，其特征在于，所述装置包括：

第一查找单元，用于遍历至少一个组件，查找使用者所需的组件；

第一获取单元，用于从预先创建的第一文件中获取使用说明，所述第一文件独立于保存源码的文件；

第二获取单元，用于从预先创建的第二文件中获取示例代码，所述第二文件独立于保存源码的文件，并且所述第二文件中的示例代码能够运行；

生成单元，用于由获取的所述使用说明和所述示例代码生成组件的说明文档。

7.根据权利要求6所述的装置，其特征在于，

所述第一获取单元包括：

第二查找单元，用于根据grunt的配置信息中预先定义的所述第一文件的文件名称查找所述使用说明；

所述第二获取单元包括：

第三查找单元，用于根据grunt的配置信息中预先定义的所述第二文件的文件名称查找所述示例代码。

8.根据权利要求7所述的装置，其特征在于，所述生成单元包括：

写入单元，用于将获取的所述使用说明和所述示例代码写入grunt的配置信息中；

第三获取单元，用于获取所述说明文档的html页面模板；

结合单元，用于将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合，从而生成html文档形式的说明文档。

9.根据权利要求8所述的装置，其特征在于，所述结合单元包括：

第一解析单元，用于将配置信息中的所述使用说明和所述示例代码解析到所述html页面模板中。

10.根据权利要求8所述的装置，其特征在于，所述结合单元包括：

第二解析单元，用于将配置信息中的所述示例代码解析到所述html页面模板中；

保存单元，用于将配置信息中的使用说明保存在所述html页面模板中。