中文字幕av专区_日韩电影在线播放_精品国产精品久久一区免费式_av在线免费观看网站

溫馨提示×

溫馨提示×

您好,登錄后才能下訂單哦!

密碼登錄×
登錄注冊×
其他方式登錄
點擊 登錄注冊 即表示同意《億速云用戶服務條款》

自動生成 java 項目 markdown 文檔框架-01-入門使用

發布時間:2020-07-21 16:18:40 來源:網絡 閱讀:137791 作者:葉止水ryo 欄目:編程語言

設計初衷

節約時間

Java 文檔一直是一個大問題。

很多項目不寫文檔,即使寫文檔,對于開發人員來說也是非常痛苦的。

不寫文檔的缺點自不用多少,手動寫文檔的缺點也顯而易見:

  1. 非常浪費時間,而且會出錯。

  2. 無法保證及時更新。代碼已經變了,但是文檔還要同步修改。需要強制人來維護這一種一致性。這很難。

為什么不是 swagger-ui

java 的文檔有幾類:

  1. jdk 自帶的 doc 生成。這個以前實踐給別人用過,別人用 C#,看到 java 的默認文檔感覺很痛苦。

就算是我們 java 開發者,也很討厭看 jdk 的文檔。看著不美觀,也很累。

  1. swagger-ui 是基于 java 注解的文檔生成工具。相對而言比較優雅,也非常強大。

但是缺點也是有的。開發人員要寫 jdk 原來的注釋+注解。注解太多,導致寫起來也很痛苦,大部分開發者后來還是選擇了放棄。

那么問題來了?我們怎么辦才能盡可能的讓開發人員,和文檔閱讀人員都樂于接受呢?

jdk 自帶的 doc 就是基于 maven 插件的,本項目也是。

區別如下:

  1. 盡可能的保證和 Java 原生注釋一致,讓開發者很容易就可以使用。

  2. 盡可能的信息全面,但是文檔簡潔。讓文檔的閱讀者享受到等同于手寫文檔的體驗。

  3. 將信息的獲取和生成區分開。方便用戶自己定義自己的輸出方式。

IDOC

i-doc 項目簡介

為 java 項目生成項目文檔。

基于原生的 java 注釋,盡可能的生成簡介的文檔。用戶可以自定義自己的模板,生成自己需要的文檔。

特性

  • 基于 maven 項目生成包含大部分信息的元數據

  • 默認支持 markdown 簡化文檔的生成,支持自定義模板

  • 支持用戶自定義文檔生成器

  • 支持用戶自定生成文檔的類過濾器

新特性

  • 添加字段類型別名,支持用戶自定義

快速入門

需要

jdk1.8+

maven 3.x+

maven 引入

使用 maven 引入當前 idoc 插件。

<build>
    <plugins>
        <plugin>
            <groupId>com.github.houbb</groupId>
            <artifactId>idoc-core</artifactId>
            <version>0.1.0</version>
        </plugin>
    </plugins>
</build>

測試對象的創建

為了演示文檔,我們創建了一個 Address 對象。

package com.github.houbb.idoc.test.model;

/**
 * 地址
 * @author binbin.hou
 * @since 0.0.1
 */
public class Address {

    /**
     * 城市
     */
    private String country;

    /**
     * 街道
     */
    private String street;

    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }
}

執行插件

mvn com.github.houbb:idoc-core:0.0.2:idoc

命令行日志信息

[INFO] ------------------------------------ Start generate doc
[INFO] 共計 【1】 個文件待處理,請耐心等待。進度如下:
==================================================================================================== 100%
[INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator
[INFO] ------------------------------------ 文檔信息如下:

[類名] com.github.houbb.idoc.test.model.Address
[類信息] {"comment":"地址","docAnnotationList":[],"docFieldList":[{"comment":"城市","name":"country","type":"java.lang.String"},{"comment":"街道","name":"street","type":"java.lang.String"}],"docMethodList":[{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getCountry","seeList":[],"signature":"getCountry()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"country","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setCountry","seeList":[],"signature":"setCountry(country)"},{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getStreet","seeList":[],"signature":"getStreet()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"street","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setStreet","seeList":[],"signature":"setStreet(street)"}],"docTagList":[{"lineNum":5,"name":"author","parameters":["binbin.hou"],"value":"binbin.hou"},{"lineNum":6,"name":"since","parameters":["0.0.1"],"value":"0.0.1"}],"fullName":"com.github.houbb.idoc.test.model.Address","modifiers":["public"],"name":"Address","packageName":"com.github.houbb.idoc.test.model"}

[INFO] ------------------------------------ Finish generate doc

Markdown 的生成

參考 03-自定義生成文件過濾器

效果參見 idoc-test-全部文檔.md

進一步學習

00-項目概覽

01-設計初衷

02-插件的參數配置

03-自定義生成文件過濾器

04-字段類型別名支持

開源地址

idoc

向AI問一下細節

免責聲明:本站發布的內容(圖片、視頻和文字)以原創、轉載和分享為主,文章觀點不代表本網站立場,如果涉及侵權請聯系站長郵箱:is@yisu.com進行舉報,并提供相關證據,一經查實,將立刻刪除涉嫌侵權內容。

AI

新泰市| 嘉善县| 武威市| 连江县| 左贡县| 高州市| 凌海市| 元阳县| 新郑市| 商洛市| 新余市| 会宁县| 陇川县| 宝清县| 上栗县| 百色市| 突泉县| 金华市| 上犹县| 佛冈县| 雷州市| 龙海市| 巩义市| 通化县| 崇明县| 阳高县| 晋城| 南投市| 泾阳县| 仲巴县| 永顺县| 临武县| 密山市| 日土县| 绥滨县| 绵竹市| 吉安市| 眉山市| 行唐县| 繁昌县| 兴山县|