Maven项目自动更新/修复Javadoc

前言

创作开始时间：2022年8月29日23:55:27

有时候修改了函数签名（比如参数）之后经常忘记同步修改javadoc，导致在用maven生成javadoc（调用javadoc plugin）的时候，会报各种错误，如：@param name not found。一个一个手动修改的话不知道要何年何月，因此本文探索一下如何自动更新javadoc。

问题描述

环境：

• maven 3
• jdk 11

我的javadoc插件：（在pom.xml文件中声明）

<plugin>
				<groupId>org.apache.maven.pluginsgroupId>
				<artifactId>maven-javadoc-pluginartifactId>
				<version>3.4.1version>
				<executions>
					<execution>
						<id>attach-javadocsid>
						<goals>
							<goal>jargoal>
						goals>
					execution>
				executions>
			plugin>
1
2
3
4
5
6
7
8
9
10
11
12
13

在mvn clean package -DskipTests的时候，出现报错信息，片段如下：

100 errors
100 warnings
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] mcrepair_parent .................................... SUCCESS [  0.560 s]
[INFO] utils .............................................. SUCCESS [  2.519 s]
[INFO] mcrepair ........................................... FAILURE [ 11.052 s]
[INFO] mcstudy ............................................ SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 14.742 s
[INFO] Finished at: 2022-08-29T23:14:44+08:00
[INFO] Final Memory: 41M/147M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.4.1:jar (attach-javadocs) on project mcrepair: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 1 - /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/MethodAdaption.java:42: warning: no description for @param
[ERROR] * @param methodSnippet
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/MethodAdaption.java:43: warning: no description for @param
[ERROR] * @param candMsList
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/MethodAdaption.java:44: error: @param name not found
[ERROR] * @param covInfoMap
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/MethodAdaption.java:44: warning: no description for @param
[ERROR] * @param covInfoMap
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/MethodAdaption.java:69: warning: no @return
[ERROR] public boolean adapt() {
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/SootOriUtil.java:38: error: @param name not found
[ERROR] * @param sootClass  soot class
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/SootOriUtil.java:39: error: @param name not found
[ERROR] * @param javaMethod java method
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/SootOriUtil.java:42: warning: no @param for className
[ERROR] public static SootMethod getTargetMethod(String className, MethodSnippet ms) {
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/SootOriUtil.java:42: warning: no @param for ms
[ERROR] public static SootMethod getTargetMethod(String className, MethodSnippet ms) {
[ERROR] ^
[ERROR] /mnt/data/2021_11_multi_chunk_repair/APRConfig/apr_tools/TransplantFix_industrial/mcrepair/src/main/java/apr/aprlab/repair/adapt/entities/EntityInMethod.java:61: warning: no description for @param
[ERROR] * @param simpleClassName
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

解决方案

在terminal运行如下代码：

 mvn javadoc:fix -DcomparisonVersion=1.0
1

然后按yes就行。

备注：建议用git管理maven项目，在运行以上代码之前先commit提交一版，以方便不时之需（如回退版本）

但是我发现运行了之后，再次package的时候，还是有一些错误，只不过从100个错误变成了29个。。。

29 errors
7 warnings
1
2

行吧，自己再手动改改把。

各个错误的修复方法：

• error: bad HTML entity 把&换成&
  对于其他的html entity，比如->，可以用{@literal xxx_your_text}这个环境包起来，此处参考：https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

最后终于编译成功了。

小结

以上。

创作结束时间：2022年8月30日12:32:48

参考文献

• https://stackoverflow.com/questions/47418027/javadocs-param-name-not-found
• https://www.thinbug.com/q/2260359 这个eclipse的设置只是自动报错，不能自动修改。
• https://maven.apache.org/plugins/maven-javadoc-plugin/examples/fix-javadocs.html 这个是maven官方仓库给出的方案，被我采纳了。