本文來自網易雲社區
作者：王飛
一、前言
一切問題的起源就是來自一個問題“為什么我打的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中的樣子
參考資料
網易雲免費體驗館，0成本體驗20+款雲產品！
更多網易研發、產品、運營經驗分享請訪問網易雲社區。
相關文章：
【推薦】 SVN遷移到GIT