为什么我打的jar包没有注解?

勿忘初心2018-10-15 13:25

本文来自网易云社区

作者:王飞

一、前言

一切问题的起源就是来自一个问题“为什么我打的jar包没有注解?”,带着这个疑问查了一圈资料,原来问题主要是在没有将源码中的注释进行抽取打包,自然我们在引用jar包的时候,无法获得注解。

二、让maven发布带上注解

这个方法很简单,只需在build->plugins下面中增加javadoc的插件来打包资源包,这样打包的时候就会额外增加一个以javadoc结尾的jar包。javadoc的组件添加源码如下:

<!--配置生成Javadoc包--><plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.4</version>
    <configuration>
        <encoding>UTF-8</encoding>
        <aggregate>true</aggregate>
        <charset>UTF-8</charset>
        <docencoding>UTF-8</docencoding>
    </configuration>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions></plugin>

三、什么是javadoc

javadoc居然可以解决jar包中代码注释的问题,那么什么是javadoc呢? 百度百科中的解释是:javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。 javadoc的注解方式是有一定格式的,常用的注解方式有

标签 说明 JDK 1.1 doclet 标准doclet 标签类型
@author 作者 作者标识 包、 类、接口
@version 版本号 版本号 包、 类、接口
@param 参数名 描述 方法的入参名及描述信息,如入参有特别要求,可在此注释。 构造函数、 方法
@return 描述 对函数返回值的注释 方法
@deprecated 过期文本 标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在,以此告之开发者不应再用这个API。 包、类、接口、值域、构造函数、 方法
@throws异常类名 构造函数或方法所会抛出的异常。
构造函数、 方法
@exception 异常类名 同@throws。 构造函数、 方法
@see 引用 查看相关内容,如类、方法、变量等。 包、类、接口、值域、构造函数、 方法
@since 描述文本 API在什么程序的什么版本后开发支持。 包、类、接口、值域、构造函数、 方法
{@link包.类#成员 标签} 链接到某个特定的成员对应的文档中。
包、类、接口、值域、构造函数、 方法
{@value} 当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值。
√(JDK1.4) 静态值域

此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签,由于不常使用,我们不展开叙述,感兴趣的读者可以查看帮助文档。

注释非常重要,不能随意增加或者修改成其他内容,否则会只是报错,打包不通过。如果一个类或者方法前增加了注解,且方法中存如param,return 或者throws时,注解中不添加的话也是会抛出警告的。所以注解要加的清晰易懂且符合规范。更多的关于javadoc的注解使用,可以通过参考资料查看其它更丰富的内容。

虽然javadoc能解决大部分的代码注释问题,但像是在代码方法中的注解呢?这个要是也想分享出来,靠javadoc就比较困难了。

四、引出的另外一个问题,如何让别人可以通过maven获取的源码

伴随着注释打包发布的更高需求的打包就是将源码一同打包。那么如何在maven仓库发布的时候,可以将自己的源码发出去呢?这个就需要我们maven的另一个插件了——sources。 和javadoc一样,只需在build->plugins下面中增加sources的插件来打包资源包,这样打包的时候就会额外增加一个以sources结尾的jar包。sources的组件添加源码如下:

<!--配置生成源码包--><plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.0.1</version>
    <executions>
        <execution>
            <id>attach-sources</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions></plugin>

将源码也打包发布后,对方在调用我们jar报的时候,可以通过IDEA可以手动加载源码,查看更多的代码内容,而不是只能通过反编译的代码去看,没有任何的注解,要是代码质量不是太高的话,对方是很难理清头绪的。

五、最终效果

打包完成后的样子


maven仓库中的样子


IDEA中的样子


参考资料

  1. Maven打包生成源码包和Javadoc包

  2. maven 打包之后为什么 class 文件中没有注释了?

  3. 百度百科javadoc

  4. maven下载源代码,解决中文注释为乱码的问题

  5. JavaDOC注释使用方法


网易云免费体验馆,0成本体验20+款云产品!

更多网易研发、产品、运营经验分享请访问网易云社区


相关文章:
【推荐】 流式断言器AssertJ介绍
【推荐】 一个只有十行的精简MVVM框架(上篇)