项目接口文档输出插件 javaDoc dokka doxygen的使用与配置 doxygen输出界面的美化方法

JavaDoc

• 因合作开发的普遍流行，一个项目的结构文档在项目中起到了一个至关重要的作用，下面介绍三款可以自动生成javaDoc文件的插件，其中两款适用于Android Studio

Android Studio自带javaDoc工具

流程

• 点击菜单栏——Tools——Generate JavaDoc

• 配置javaDoc的参数

  command line and arguments输入内容：-encoding utf-8 -charset utf-8

  不添加这一行可能会生成文档失败

• 点击Generate生成文档，文档生成完毕后自动浏览器显示

优缺点

优点

• 简介方便，不需要自主配置就能一键生成

缺点

• 文档界面比较过时，不够美化
• 只能解析java文件，不能够适配kotlin文件

dokka

官网

• [dokka github](Kotlin/dokka: API documentation engine for Kotlin (github.com))
• [kotlinlang.org](Introduction | Kotlin Documentation (kotlinlang.org))

简介

• 

• 以下是使用dokka生成的各类文档界面

  

配置流程

gradle

1. 在项目的gradle中加入引入这行参数 id(“org.jetbrains.dokka”) version “1.9.10” apply false

   import org.gradle.kotlin.dsl.apply
   import org.gradle.kotlin.dsl.version
   
   // Top-level build file where you can add configuration options common to all sub-projects/modules.
   plugins {
       id("com.android.application") version "8.2.2" apply false
       id("org.jetbrains.kotlin.android") version "1.9.22" apply false
       id("org.jetbrains.dokka") version "1.9.10" apply false
   }
   

2. 在你的app的gradle或者module的gradle中写入id(“org.jetbrains.dokka”)

   plugins {
       id("com.android.application")
       id("org.jetbrains.kotlin.android")
       id("org.jetbrains.dokka")
   }
   

3. 引入完成之后，点击右上方的sync now，同步一下gradle文件

4. 然后点击右侧边栏的gradle图标，会出现如下图所示的文件

5. 若没有出现documentation这个目录，点击上方的设置图标

6. 选中以下选项，再次同步就会出现该目录栏

7. 这里可以选择导出为gfm、html、javadoc或者jekyll

8. gfm（github 风格的markdown）

   

9. html

   

   

10. javadoc

    

    

11. kekyll

    

优缺点

优点

• 界面美观
• 多种文档格式可供选择
• 同时支持java和kotlin语言

缺点

• 只支持java和kotlin
• 需要在Android Studio引入才能使用

doxygen

官网

• [Doxygen homepage](Doxygen homepage)
• [Doxygen github](doxygen/doxygen: Official doxygen git repository (github.com))

简介

• 

  Doxygen 是一个广泛应用的文档生成工具，它可以从项目中自动解析文件，生成对应的文档，它能解析有关的类、函数、以及变量信息，生成html等格式的输出

• Doxygen默认支持C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Fortran and D语言格式的文件解析

下载

1. 在官网下载对应版本的软件

   

2. 选择默认的安装选项即可，可以修改安装路径

3. 安装完成打开GUI可视化界面

界面介绍

1. 配置界面

   • project

     

     这里主要配置了一个输入 输出

   • Mode

     

     这里可以选择项目的语言，以便更精确的生成说明文档

   • Output

     

   • Diagrams

     

2. 其他配置界面

   • Project

     

     这几项内容是根据之前配置的生成的

     

     这里可以选择生成的文档的语言

     

     JAVADOC_AUTOBRIEF 勾选该标签后，会自动将注释的第一行（直到第一个英文句号.）解释为简要描述。这不适合中文习惯，因为要使用英文句号.而不能使用中文句号。不勾选该标签则应该显式使用\brief命令引入简要描述。

     JAVADOC_BANNER 如果使用了/***************（两个以上的星号）开头的注释，默认是不提取该注释的，若希望把它当作/**一样处理，则需要勾选该标签

     TAB_SIZE 该标签用于设置将代码片中的制表符替换为多少个空格

   • Build

     

     这里个用于配置解析的内容 第一个是解析全部 第二个解析私有函数等 可以按需求勾选

   • Input

     

     这个是之前选择了解析子目录 自动勾选上的

   • HTML

     因为后面我添加了界面风格，这个部分后面单独说

3. Run

   • 

   • 

界面美化

• 因为生成出来的文档和AS自带的javaDoc工具所生成出来的有异曲同工之妙——老土，所以在我的不懈努力下，找到了美化的插件，美化结果如下图所示

  

• [美化插件地址](jothepro/doxygen-awesome-css: Custom CSS theme for doxygen html-documentation with lots of customization parameters. (github.com))

配置介绍

1. 首先，先点击上面的github地址，将源码下下来，保存在一个地址，如下图所示

   

2. 根据作者在readme里面的介绍

   

   我们需要配置如下几个参数

3. 打开doxygen GUI 的html配置界面

   

   找到该参数 将之前下载的红框里的css文件选中添加进去

   

   找到改参数 选择风格为light

   

   找到这三个参数 按照图中所示的进行勾选

4. 勾选完成之后，去到Run界面，开始生成文档，生成之后的文档就如上方所示

优缺点

优点

• 支持的语言类型众多
• 不需要在项目中引入或者在编译软件中下载插件，直接下载软件就能使用
• 支持生成图表，各类之间的关系更加明了

缺点

• 不支持kotlin语言（据说可以自己编写一个插件进去，后续研究一下）
• 界面比较丑陋（通过引入css文件得以解决）

其他

1. 所有的配置会在再一次进入时清零，因此可以通过保存该配置来缩减时间 File——Save as 下次进来open该文件即可

2. VS code 有自动加入注解的插件 Doxygen Documentation Generator 可以跟这个进行配套使用