CN108021390A - 一种Java应用编程接口的文档缺陷自动修复方法 - Google Patents

Abstract

本发明公开了一种Java应用编程接口的文档缺陷自动修复方法，其对Java API中有缺陷的文档进行自动修复，分别提取Java API文档的参数相关约束描述信息和执行代码中的异常信息及其触发条件处理信息，并进行比对，从而检测出文档描述中可能存在的缺陷问题，并采用基于预定义模板的方式对其进行修复。本发明提高了Java API文档对API代码中与参数相关的异常描述的准确性，进而提高软件质量。

Description

一种Java应用编程接口的文档缺陷自动修复方法

技术领域

本发明属于软件工程技术领域，尤其涉及一种Java应用编程接口(API)的注释文档对于执行代码中参数的实际约束条件描述错误或没有描述，即注释文档有缺陷时，对文档进行自动修复的方法。

背景技术

随着软件项目规模的不断增大，高效复用代码成为业界的追求目标，而使用应用编程接口(Application Programming Interface,即API)是其中一项重要的技术手段。API一般是一些开放的函数接口，其代码底层实现对开发人员透明，从而将精力集中于业务逻辑，提高开发效率。

开发者通过API文档了解接口的约束条件，以达到正确使用API的目的。在本发明中，我们主要针对的Java API文档是指每一个开放的方法中，由人工编写、具有一定组织结构、以代码注释形式存在于源代码中的Javadoc文档。这样的文档更注重细节定义，如参数取值范围、参数类型限制以及该方法的返回值值域、类型等。

高质量的API文档，应该清楚地描述出调用该接口时需要满足的相关约束条件。模糊甚至错误的API文档，会造成软件开发人员理解困难甚至是理解错误。在实际情况中，由于人为撰写可能存在的错漏、文档和代码更新进度不一致等原因，导致了文档会存在很多缺陷的情况。

国内外有许多研究者对软件文档进行探讨和研究，但是少有针对文档中异常约束条件描述问题的研究。以下将介绍关于软件文档研究的相关几个主要方面。

研究软件文档与执行代码之间的关系，就必须分析执行代码。目前，多数相关研究采用静态分析技术作为技术手段。Raymond等人提出了一种自动生成Java API文档的方法，通过定位异常、捕捉异常触发条件，并根据触发条件中的代码信息生成自然语言描述文档。另外，Mohamed等人提出了利用符号执行技术，捕捉代码中的约束限制，并将提取出的约束条件与已有的Java API文档中的相关描述进行对比，检测不一致情况。但是该方法并未考虑到Java API方法之间存在的调用关系问题。

另外，也有通过动态分析的方法来检测文档中存在不一致性，其主要的思路是提取文档中相关约束，根据约束生成一系列的测试用例来对代码进行检测。该方法主要适用于参数的空值约束。目前没有更多研究将该方法应用于检测文档的其他类型约束。

此外，Gias Uddin等人通过调研发现，API文档的不完整性、模糊性和错误性都会对API的理解产生非常重要的影响，以至于无法正确使用API。因此，对API文档进行修复是非常有必要的。

发明内容

针对于上述现有技术的不足，本发明的目的在于提供一种Java应用编程接口的文档缺陷自动修复方法，本发明可针对应用编程接口文档的异常触发条件描述不正确或未描述的情况进行修复，提高Java API文档的完整性和准确性。

为达到上述目的，本发明采用的技术方案如下：

本发明的一种Java应用编程接口的文档缺陷自动修复方法，包括步骤如下：

1)提取源代码中每个方法的执行代码部分以及注释文档部分，分别进行分析；

2)遍历当前分析目标的所有方法，提取每个方法的抛出异常类型及其触发条件，并建立目标工程源代码中各方法之间的调用关系库；

3)对Java API的执行代码部分进行分析，对于每一个方法，首先分析当前方法的异常触发的约束条件，然后根据上述调用关系库，递归分析调用方法中异常触发的约束条件，将当前方法和调用方法中异常触发的约束条件进行合并，即当前方法异常触发的约束条件集合；

4)对于目标工程中的每个方法，利用启发式方法分析其注释文档，得到文档中关于异常触发的约束条件；

5)对于目标工程中的每个方法，将步骤3)和4)中的约束条件进行对比，找到文档缺陷；

6)将步骤3)中的约束条件根据预定义模板生成相应的自然语言，即给出的修复建议，将修复建议定位到对应的方法位置，推荐给用户，以便对文档进行修改，从而完成了对API文档缺陷的自动修复。

优选地，所述步骤1)中的注释文档指每个Java API方法对应的JavadocAnnotation注释文档，这是一种具有半结构特征的文档。

优选地，所述步骤1)中的执行代码指执行API功能的程序代码。

优选地，所述步骤2)中抛出异常类型指在throw语句中被抛出的异常对象所属类型，句式为：

thrownew Exception(Description)

其中，Exception指所有抛出异常的类型，Description指代码中抛出异常时的提示信息。

优选地，所述步骤3)中异常触发的约束条件指代码执行到抛出异常的throw语句时参数的设置条件，该条件中必须有至少一个当前方法的参数参与。

优选地，所述步骤2)中调用关系库利用静态分析技术，获取方法之间存在直接参数传递现象的调用关系。

优选地，所述存在直接参数传递现象的调用关系指：某个方法将自己的某个参数作为形参传递给其调用的另一个方法，则称这两个方法之间是一种存在直接参数传递的调用关系。

优选地，所述步骤3)中递归分析的具体步骤还包括：提前设置调用深度阈值、每层方法刷新异常信息的触发条件和涉及参数信息。

优选地，所述步骤4)中启发式方法指对于某个异常信息，逐个查看注释文档中的特定条目，针对当前异常条件中所涉及到的参数，根据启发式规则生成相应参数的约束条件。

优选地，所述文档有缺陷基于这样的假设，即代码中的异常触发的约束条件是完全正确的，若遍历整个文档，找不到与其相匹配的约束条件，则认为文档未对此异常进行准确的描述，即文档有缺陷。

优选地，所述步骤6)中若文档有缺陷，则将代码中提取的异常触发的约束条件，依据预定义的自然语言模板将其转化为自然语言，即文档缺陷修复建议。

优选地，所述步骤6)中在生成自然语言后，通过Eclipse插件的形式，定位到该API所在位置，将修复建议推送给用户，从而完成对API文档的修复。

本发明的有益效果：

本发明利用静态代码分析的手段，对Java API中有缺陷的文档进行自动修复，分别提取Java API注释文档和执行代码中的异常信息及其触发条件，并与文档的相应描述进行比对，从而检测出文档中可能存在的缺陷问题，并对其进行修复，以提高Java API文档对抛出异常描述的准确性，进而提高软件质量。

附图说明

图1为本发明文档缺陷自动修复方法的原理图。

具体实施方式

为了便于本领域技术人员的理解，下面结合实施例与附图对本发明作进一步的说明，实施方式提及的内容并非对本发明的限定。

参照图1所示，本发明的一种Java应用编程接口的文档缺陷自动修复方法，包括步骤如下：

(1)核心数据结构

基于本发明的检测策略，定义一个基本的元数据结构，用于存储代码中可能产生的异常及其相关信息。将其命名为InfoBox，每个InfoBox需要存储异常类型、异常触发条件、所涉及的参数以及该异常所属的方法信息等。

由于每个InfoBox只记录一条异常相关信息，所以对于每个API方法，可能提取出多个InfoBox数据，而这些异常信息都应该在该方法对应的文档中得到表述。若当前API不存在文档和代码不一致性，则它们之间的关系应满足如下公式：

公式中，c_i代表该API方法中第i个InfoBox所包含的参数约束条件信息，c_doc表示该API方法对应的文档中表述的所有约束条件信息。如果发现某个InfoBox所包含参数约束信息不满足上述公式(1)，则认为该API文档存在缺陷。

分析的文档具体是指Java源代码中存在的Javadoc Annotation信息，这一类文档具有一定的结构特征。每个Java方法对应一块Javadoc信息块，而每一个信息块中存在多个条目(directive)，每个条目主要分为3个部分：类型描述、关键词、描述语句；其中类型描述一般以@开头，常见的有@param、@throws以及@exception等，表示该条目主要的内容；关键词随条目类型的不同而具有不同的意义，如@param中关键词是相关的参数名，而@throws和@exception中关键词是抛出异常类型；描述语句是一段自然语言文字信息。

(2)调用关系库的构建

该步骤将针对源代码项目中各方法之间存在的调用关系进行分析。同时，由于研究对象为程序异常，并且主要针对其触发条件中相关参数需要满足的约束条件，故仅关注一种存在直接参数传递的调用关系。

上述直接参数传递的调用关系是指，如果某方法A中调用了方法B，并将该方法A的某个参数p(或者某些参数，这里仅举一个参数进行说明)作为形参直接传递给方法B的这样一种调用关系。例如，javax.swing.JTabbedPane类中的insertTab(String title,Iconicon,Component component,String tip,int index)方法调用了java.awt.Container中的addImpl(Component comp,Object constraints,int index)方法，并将其component参数作为形参直接传递给后者相应的参数位。即insertTab方法与addImpl方法之间存在直接参数传递的调用关系。

这种参数传递的特征在于：对于参与调用关系的两个方法，二者之间传递的参数需要满足同样的约束条件。如果在被调方法中由于参数不满足约束条件而导致异常抛出，那么在主调方法对应的文档中也同样应该对这个异常进行相应的描述。

利用静态分析的手段构建调用关系库。具体的，在实践中，采用的是eclipse中的callhierarchy开源模块作为具体的技术实施手段来获取调用关系，由于是静态分析工具，不考虑运行时由方法重载引起的动态调用情况。

(3)执行代码分析

采用一种二阶段的处理方式对执行代码进行分析，提取其中的异常信息及其触发条件。其中，第一阶段逐个分析每个方法中存在的异常信息，即提取InfoBox。第二阶段加入调用关系的分析，获取该方法在递归调用其他方法中还可能抛出的异常信息，即递归提取InfoBox。

在第一阶段中，利用eclipse提供的JDT-AST工具进行语法树分析，进而抽取出InfoBox信息元数据。其算法思想伪代码参见表1，如下：

表1

伪代码中，用元组(m,c,p)来表示InfoBox元数据，其中，m代表异常类型，c代表其触发条件的集合，p代表触发条件中所涉及该方法的参数集合。

具体的，针对每一条子句，根据其不同的类型，进行不同的操作。大概分为3类：

a)可展开语句，如子句段落组合(在JDT中具体为一个Block对象)。针对这样的简单可展开段落，再次针对每条子句逐个进行递归搜索，体现深度优先的搜索方式；

b)异常触发语句，如throws语句(在JDT中具体为一个ThrowStatement对象)。针对这样的语句处理方式为：在返回的信息集合中新建一个InfoBox，将当前的错误触发类型以及一些基本信息记录下来，然后将信息集合返回，待上层的条件语句对它的触发条件进行补充；

c)条件语句，如if语句(在JDT中具体为一个IfStatement对象)。针对这类的处理方式为：先获取其子句的信息，递归分析并提取每个子句中存在的异常信息，组建成InfoBox集合，然后将本句的条件添加到该集合的每个信息元组上，将更新后的InfoBox集合返回。

在得到了整个信息集合之后，对于集合中每个元组，分析其触发条件，找到所有参与触发条件判断的参数，补充在元组的p部分。如此，得到了这个信息集合。此阶段最后一步，就是将获取的信息存在本地。

第二阶段将根据第一阶段获取的数据进行进一步分析。对于每一个待分析的API方法，其具体分析步骤伪代码如表2所示，如下：

表2

分析策略如下：

a)首先，提取当前方法的所有InfoBox异常信息；

b)查看调用关系库，获取当前方法的所有调用关系；

c)对于每个调用关系，递归分析每个调用方法的异常信息，并将其返回，形成当前方法的一个异常信息集合；

d)对于每个异常信息，根据主调、被调方法之间对应的参数名，更新其中的触发条件以及参数信息，使之和上一层的参数名匹配。

为了避免调用关系形成闭环，在分析开始时，需要设置一个递归深度的阈值。当达到预计的分析深度时，则停止向下的递归分析。

(4)API文档自然语言分析

API文档对约束条件的描述具有自然语言特性，因此，本发明提出引入自然语言处理的相关思想和技术，对API文档的描述语句进行语义理解，提取其中的约束条件，用于与静态分析过程中提取的相关约束进行对比，继而检测不一致问题。

具体的，本方法主要包含以下三个步骤：

1)预处理阶段；将一些领域专属词项进行替换，对一些特殊词汇进行替换处理，生成替换词汇字典。

API文档中的自然语言描述语句会出现诸如变量名、函数名(方法名)等仅在编程代码中有特殊意义的词汇(下文简称特殊词汇)。这些特殊词汇在软件文档中具有重要的意义，但同时，这些词汇可能对抽象语法树的提取以及词项依存关系的分析形成干扰。为了简化语言分析过程，同时保留特殊词汇所蕴含的重要信息，此时将对一些特殊领域词汇进行处理。主要思想是，利用正则表达式，搜索和匹配这类特殊词汇，将之替换成能被识别的特殊词项。

2)语句拆分；根据目标语句语法树结构将含有多个约束条件的复合语句拆分成数个只含有单个约束条件的原子语句。

一个条目可能含有数个自然语句。而一个自然描述语句中，可能含有多个约束条件。由于每个约束所约束的行为不同，可能会对后续的句子理解过程造成偏差，因此需要简化复杂的语句。语句拆分阶段，利用一些启发式的解析规则，将含多个约束条件的复合语句拆分成数条仅有单个约束条件的原子语句，便于接下来的语义理解和分析。

3)语义理解；根据词项依存关系，对原子语句的描述逻辑进行理解。

经过上述阶段，仅含单个约束条件的原子语句已经被分离开来，接下来需要对这样的语句进行进一步的语义理解，从中提取出所含有的约束条件。基本思想是，根据词项之间的依存关系，定义一些启发式规则，利用规则匹配语句的依存语法，达到理解语义的目的。尽管自然语言存在一定的歧义性，导致对自然语言的理解存在一定的复杂度。幸运的是，对于API文档来说，其具备的领域特征，使得很多文档具有相同的句式。

语义理解规则具有一定的针对性，对于描述的不同种类的约束，需要用不同的启发式规则。将约束类型分为三类，即空值禁止约束、取值范围约束以及类型限制约束。本方法定义不同的启发式语义理解规则进行约束条件提取。通过对JDK中部分源代码对应的API文档描述语句的表达模式进行归纳总结，针对不同类型的约束描述，梳理出3类，共55条语义解析规则，如表3：

表3

根据启发式规则，利用关键词以及词项之间的依存关系，寻找约束主体，同时确定约束行为。

(4)比较约束条件的逻辑一致性

通过上述两个步骤，分别从代码静态分析以及文档自然语言理解的过程中获取了2份约束条件。接下来，利用可满足性模型理论，对二者的约束条件进行对比，检测二者的是否一致，从而检测相应的API文档对代码约束的描述是否一致。若不一致，即文档有缺陷。

(5)文档缺陷修复

经过以上步骤，对于判定API文档有缺陷的方法，应对代码中异常触发的约束条件进行描述，根据代码分析模块获取的约束条件，以及对应的异常类型，根据具体匹配的模板，将约束条件转化为描述此异常信息的自然语言，用以对文档进行修复。然后通过Eclipse插件的形式，定位到该方法所在的位置，将文档修复建议推荐给用户，完成对API文档缺陷的修复。

具体来讲，主要考虑三类参数约束，每个类别都有可以重用的生成文本的模板，通过这种基于预定义的自然语言模板的解决方式，提供修复解决方案，来修复API文档的缺陷。其中，预定义的自然语言模板如下表4：

表4

如上表4，为保持与API文档的一致性，在生成修复建议时，会与原有文档类似的添加相应的tag。因都与异常有关，所以添加的tag均为@throws，并且在后面加上提取的相应的异常名称。

修复建议生成后，通过Eclipse插件的形式，首先定位到原方法所在的位置，针对每条缺陷所生成的推荐修复结果会显示到视图右侧的文本框中，中间的文本框显示的是所有的缺陷信息。这样，就可以逐条的对文档进行修复。

综上所述，本发明通过上述(1)至(5)，对Java API文档是否有缺陷进行检测。如果API文档有缺陷，则通过文档缺陷修复模块对文档进行修复。

参照表5，其为本发明的准确度验证的数据集，如下：

表5

参照表6为本发明对API文档缺陷准确度评估，如下：

表6

根据不同的约束类型，对本发明方法的准确性进行评估。总体而言，本发明方法的准确率为67.4％，召回率75.7％，可以看出，本发明方法具有显著的效果。其中，对于空值禁止的检测效果最好，达到75.2％的准确率以及84.7％的召回率。

对于给出的修复建议，从中抽取160份样本，每份样本都由三人从以下四个方面进行打分，如下表7：

表7

	问题	分值
			问题一	是否反映了代码约束	(5-1)
问题二	是否有利于更好的使用和理解API	(5-1)
			问题三	修复建议是否含有无关信息	(5-1)
问题四	修复建议是否简明易懂	(5-1)

其中5分代表最好，4分代表较好，3分代表中立，2分代表一般，1分代表最差。

对于数据集，实验结果如表8：

表8

各问题的平均分如下表9：

表9

问题一	问题二	问题三	问题四	总分
					4.49	3.99	4.51	4.17	17.16

可见，在总分为20分的评估中，缺陷修复的结果可以给到17.16分，取得了良好的实验效果，证明本发明的缺陷修复方法是可行有效的。

表10为本发明普适度验证的数据集，如下：

表10

缺陷准确度的评估如下表11：

表11

从缺陷修复结果中抽取100份样本，每份样本由三人打分，缺陷修复结果的评分如下表12：

表12

各问题的平均分如下表13：

表13

问题一	问题二	问题三	问题四	总分
					4.49	4.14	4.53	4.39	17.55

可以看到，本发明依然能保持较好的修复效果。对于缺陷检测能够达到74.7％的准确率以及89.4％的召回率。而修复建议在满分为20分的情况下，取得17.55的高分。

本发明具体应用途径很多，以上所述仅是本发明的优选实施方式，应当指出，对于本技术领域的普通技术人员来说，在不脱离本发明原理的前提下，还可以做出若干改进，这些改进也应视为本发明的保护范围。

Claims (10)

1.一种Java应用编程接口的文档缺陷自动修复方法，其特征在于，包括步骤如下：

1)提取源代码中每个方法的执行代码部分以及注释文档部分，分别进行分析；

2)遍历当前分析目标的所有方法，提取每个方法的抛出异常类型及其触发条件，并建立目标工程源代码中各方法之间的调用关系库；

3)对Java API的执行代码部分进行分析，对于每一个方法，首先分析当前方法的异常触发的约束条件，然后根据上述调用关系库，递归分析调用方法中异常触发的约束条件，将当前方法和调用方法中异常触发的约束条件进行合并，即当前方法异常触发的约束条件集合；

4)对于目标工程中的每个方法，利用启发式方法分析其注释文档，得到文档中关于异常触发的约束条件；

5)对于目标工程中的每个方法，将步骤3)和4)中的约束条件进行对比，找到文档缺陷；

6)将步骤3)中的约束条件根据预定义模板生成相应的自然语言，即给出的修复建议，将修复建议定位到对应的方法位置，推荐给用户，以便对文档进行修改，从而完成了对API文档缺陷的自动修复。

2.根据权利要求1所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤2)中抛出异常类型指在throw语句中被抛出的异常对象所属类型，句式为：

thrownew Exception(Description)

其中，Exception指所有抛出异常的类型，Description指代码中抛出异常时的提示信息。

3.根据权利要求2所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤3)中异常触发的约束条件指代码执行到抛出异常的throw语句时参数的设置条件，该条件中必须有至少一个当前方法的参数参与。

4.根据权利要求1所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤2)中调用关系库利用静态分析技术，获取方法之间存在直接参数传递现象的调用关系。

5.根据权利要求4所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述存在直接参数传递现象的调用关系指：某个方法将自己的某个参数作为形参传递给其调用的另一个方法，则称这两个方法之间是一种存在直接参数传递的调用关系。

6.根据权利要求1所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤3)中递归分析的具体步骤还包括：提前设置调用深度阈值、每层方法刷新异常信息的触发条件和涉及参数信息。

7.根据权利要求1所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤4)中启发式方法指对于某个异常信息，逐个查看注释文档中的特定条目，针对当前异常条件中所涉及到的参数，根据启发式规则生成相应参数的约束条件。

8.根据权利要求7所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述文档有缺陷基于这样的假设，即代码中的异常触发的约束条件是完全正确的，若遍历整个文档，找不到与其相匹配的约束条件，则认为文档未对此异常进行准确的描述，即文档有缺陷。

9.根据权利要求8所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤6)中若文档有缺陷，则将代码中提取的异常触发的约束条件，依据预定义的自然语言模板将其转化为自然语言，即文档缺陷修复建议。

10.根据权利要求1所述的Java应用编程接口的文档缺陷自动修复方法，其特征在于，所述步骤6)中在生成自然语言后，通过Eclipse插件的形式，定位到该API所在位置，将修复建议推送给用户，从而完成对API文档的修复。