一种生成说明文档的方法和装置的制造方法
【技术领域】
[0001]本发明涉及计算机技术领域，尤其涉及一种生成说明文档的方法和装置。
【背景技术】
[0002]脚本语言是为了缩短传统的编写-编译-链接-运行过程而创建的计算机编程语言。JavaScript是一种应用于Web的脚本语言，已经被广泛用于Web应用开发。浏览器可以在JavaScript下编写源码来实现，不同浏览器的JavaScript源码不同。由于不同浏览器的JavaScript源码不同，所以不同的浏览器难以兼容。JavaScript框架能实现浏览器的兼容。
[0003]Angular JS是其中一种JavaScript框架。由于Angular JS当前很热门，所以程序开发人员热衷于基于Angular JS来开发组件。众所周知的是，在基于Angular JS对组件进行开发的过程中，程序开发人员开发的组件需要有相应的说明文档，以向组件的使用者说明所开发的组件如何使用。
[0004]当前，生成说明文档的方法依赖于程序开发人员在编写源码过程中所写的注释。该方法主要包括以下几步:获取程序开发人员在编写源码过程中写的注释，对所获取的注释进行解析以将其转换成预定义的格式，生成说明文档。说明文档通常包括使用说明和示例代码，示例代码用于向组件的使用者展示对所开发的组件调用之后的运行结果。
[0005]然而，现有的生成说明文档的方法给程序开发人员造成了很大的负担。一方面，由于该方法依赖于注释，所以程序开发人员在编写源码的过程中不得不花大量的精力和时间来写注释，结果写注释成了程序开发人员的负担；另一方面，因为说明文档包含有示例代码并且说明文档的生成依赖于注释，所以示例代码只得包含在注释中，这样所造成的结果是:在对开发的组件进行测试时，由于注释中的内容是不会被运行的，所以包含在注释中的示例代码无法被重复利用，程序开发人员只得重新准备一份测试代码来测试开发的组件。
【发明内容】
[0006]有鉴于此，本发明提供一种生成说明文档的方法和装置，以减轻程序开发人员的负担。
[0007]—种生成说明文档的方法，所述方法包括:
[0008]遍历至少一个组件，查找使用者所需的组件；
[0009]从预先创建的第一文件中获取使用者所需的组件的使用说明，所述第一文件独立于保存源码的文件；
[0010]从预先创建的第二文件中获取使用者所需的组件的示例代码，所述第二文件独立于保存源码的文件，并且所述第二文件中的示例代码能够运行；
[0011]由获取的所述使用说明和所述示例代码生成使用者所需的组件的说明文档。
[0012]优选地，从预先创建的第一文件中获取使用说明包括:
[0013]根据grunt的配置信息中预先定义的所述第一文件的文件名称查找所述使用说明；
[0014]优选地，从预先创建的第二文件中获取示例代码包括:
[0015]根据grunt的配置信息中预先定义的所述第二文件的文件名称查找所述示例代码。
[0016]优选地，由获取的使用说明和示例代码生成组件的说明文档包括:
[0017]将获取的所述使用说明和所述示例代码写入grunt的配置信息中；
[0018]获取所述说明文档的html页面模板；
[0019]将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合，从而生成html文档形式的说明文档。
[0020]优选地，将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合包括:
[0021]将配置信息中的所述使用说明和所述示例代码解析到所述html页面模板中。
[0022]优选地，将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合包括:
[0023]将配置信息中的所述示例代码解析到所述html页面模板中，并将配置信息中的使用说明保存在所述html页面模板中。
[0024]—种生成说明文档的装置，所述装置包括:
[0025]第一查找单元，用于遍历至少一个组件，查找使用者所需的组件；
[0026]第一获取单元，用于从预先创建的第一文件中获取使用说明，所述第一文件独立于保存源码的文件；
[0027]第二获取单元，用于从预先创建的第二文件中获取示例代码，所述第二文件独立于保存源码的文件，并且所述第二文件中的示例代码能够运行；
[0028]生成单元，用于由获取的所述使用说明和所述示例代码生成组件的说明文档。
[0029]优选地，所述第一获取单元包括:
[0030]第二查找单元，用于根据grunt的配置信息中预先定义的所述第一文件的文件名称查找所述使用说明；
[0031]优选地，所述第二获取单元包括:
[0032]第三查找单元，用于根据grunt的配置信息中预先定义的所述第二文件的文件名称查找所述示例代码。
[0033]优选地，所述生成单元包括:
[0034]写入单元，用于将获取的所述使用说明和所述示例代码写入grunt的配置信息中；
[0035]第三获取单元，用于获取所述说明文档的html页面模板；
[0036]结合单元，用于将配置信息中的所述使用说明和所述示例代码与所述html页面模板进行结合，从而生成html文档形式的说明文档。
[0037]优选地，所述结合单元包括:
[0038]第一解析单元，用于将配置信息中的所述使用说明和所述示例代码解析到所述html页面模板中。
[0039]优选地，所述结合单元包括:
[0040]第二解析单元，用于将配置信息中的所述示例代码解析到所述html页面模板中；
[0041]保存单元，用于将配置信息中的使用说明保存在所述html页面模板中。
[0042]可以看出，由于组件的使用说明和示例代码均以独立于源码的形式保存在各自的文件中，不再包含在源码的注释中，所以程序开发人员在编写源码的过程中无需对注释花费过多精力和时间，并且由于本发明的示例代码可以运行，所以通过本发明，示例代码还可以用于测试组件，故程序开发人员无需准备两份代码分别用于生成说明文档和测试组件，从而极大地减轻了程序开发人员的负担。
【附图说明】
[0043]图1为本发明提供的一种方法的流程图；
[0044]图2为本发明实施例最终生成的html页面形式的说明文档的示意图；
[0045]图3为本发明实施例组件架构示意图；
[0046]图4为本发明实施例提供的一种方法的流程图；
[0047]图5为本发明提供的一种装置的框图；
[0048]图6为本发明实施例提供的一种装置的框图。
【具体实施方式】
[0049]在对详细的描述进行说明之前，应该理解，用在本说明书以及权利要求中的术语及词语可能不限于普通含义或词典含义，而是在发明人能够使用新词以最佳方式解释本发明的原则下，被解释为适于本发明技术范围的含义或概念。
[0050]本发明提供实施例使得公开充分并完全涵盖本领域技术人员。对具体细节例如具体部件、装置进行阐述，以透彻理解本实施例。对本领域技术人员来说，显然，不需要采用具体的细节，实施例可以以许多不同的形式进行具体体现，而且不应该解释为对本发明范围的限制。在一些实施例中，公知装置结构、以及公知技术不再详细描述。
[0051]尽管术语第一、第二可以用来描述各种部件，这些部件不应被这些术语限制。这些术语可以仅用来将一个部件与另一部件区别开来。除非上下文清楚地指出，当使用例如“第一”、“第二”、以及其它数字术语这样的术语时，不暗指序列或者顺序。因此，在不背离实施例的原则的情况下，描述的第一部件可以被称为第二部件。
[0052]在下文中，将参考附图对本发明的示例性实施例进行详细描述。
[0053]本发明提供的方法不依赖于注释，而是将生成说明文档所需的示例代码和使用说明分别独立于源码保存为单独的文件，所以不必迫使程序开发人员在编写源码时以生成组建说明文档为目的而额外地编写大量的注释，并且由于示例代码被可执行地保存在单独的文件中而没有包含在注释中，所以在测试组件时示例代码可以被重复利用，进一步减轻了程序开发人员的负担。
[0054]请参考图1，为本发明提供的一种方法的流程图，可以包括以下步骤:
[0055]步骤101:遍历至少一个组件，查找使用者所需的组件；
[0056]步骤102:从预先创建的第一文件中获取使用者所需的组件的使用说明，第一文件独立于保存源码的文件；
[0057]步骤103:从预先创建的第二文件中获取使用者所需的组件的示例代码，第二文件独立于保存源码的文件，并且第二文件中的示例代码能够运行；
[0058]步骤104:由获取的使用说明和示例代码生成使用者所需的组件的说明文档。
[0059]需要指出的是，上述方法的执行顺序不限于此。例如，步骤102和步骤103的执行顺序可以互换。
[0060]可以看出，由于组件的使用说明和示例代码均以独立于源码的形式保存在各自的文件中，不再包含在源码的注释中，所以程序开发人员在编写源码的过程中无需对注释花费过多精力和时间，并且由于本发明的示例代码可以运行，所以通过本发明，示例代码还可以用于测试组件，故程序开发人员无需准备两份代码分别用于生成说明文档和测试组件，从而极大地减轻了程序开发人员的负担。
[0061]下面以一个更加详细的实施例介绍本发明。
[0062]首先介绍该实施例所需的安装环境。在本实施例中，基于Angular JS来开发组件，所以说明文档的html页面应由Angular JS来驱动；由于通过调用grunt来生成说明文档，所以需要安装grunt ;因为grunt运行在node js环境下，所以在安装grunt之前还需要安装node js。可以理解的，所需的安装环境不限于此。
[0063]为了更好地理解本实施例，还需要指出的是，本实施例提供的方法最终将以html页面的形式向组件使用者展示说明文档，可以理解的，向组件使用者展示说明文档的方式不限于此。html页面形式的说明文档包括使用说明、示例代码及其运行结果。请参考图2，为本实施例最终生成的html页面形式的说明文档的示意图。
[0064]请参考图3，为本实施例组件架构示意图。根据图3，本实施例可以包括多个(例如三个)组件，其中，组件I可以包括三个部分:源码、示例代码和使用说明，源码包括js源码，可选地，源码还可以包括html源码和css源码，示例代码包括示例js代码和示例html代码。