JavaDoc

https://www.cnblogs.com/linj7/p/14339381.html

Android Studio配置

plugin中找到javadoc插件后进行安装
在想要添加文档说明的方法或类上使用快捷键$${\boxed{alt}}$$ + $${\boxed{shrift}}$$ + $${\boxed{G}}$$

文档编写

过滤指定的某些public方法

规范讲不应该出现public方法的过滤，接口封装的规范
```
@deprecated
public void method() {
}

#javadoc  -nodeprecated
```
https://www.sdgsystems.com/post/hiding-javadoc-elements-with-the-exclude-tag

https://stackoverflow.com/questions/4815502/javadoc-exclude-some-public-methods-from-class
去除从父类继承的方法

todo

SDK整体结构说明

添加overview.html，并在javadoc 命令中进行指定

<HTML>
<BODY>
HollyChat Android SDK API文档
<p>
    请开发者主要参阅 {@link com.holly.sdk} 包下的类及相关接口
</p>
</BODY>
</HTML>

java package说明，在包下新增package-info.java文件(各个包要添加各个包下的package-info.java)
```
/**
 * HollySDK 对应用侧提供的业务功能类及事件回调接口
 */
package com.holly.sdk;
```

添加引用跳转

    /**
     * 加载所有成员事件返回.
     *
     * @param ret        响应码 see
     *                   {@link com.holly.sdk.model.api.ApiCode#CODE_SUCCESS},
     *                   {@link com.holly.sdk.model.api.ApiCode#CODE_ERR_USER_NOT_EXIST},
     *                   {@link com.holly.sdk.model.api.ApiCode#CODE_ERR_API_KEY}
     *                   {@link com.holly.sdk.model.api.ApiCode#CODE_ERR_NETWORK},
     *                   {@link com.holly.sdk.model.api.ApiCode#CODE_ERR_SERVER_INNER}
     * @param allMembers 所有成员，可为null
     */
    void onAllMemberResult(int ret, @Nullable List<HlContact> allMembers);

```
{@code true}
```
@see

添加外部URL引用

This creates a "See Also" heading containing the link, i.e.:
```
/**
 * @see <a href="http://google.com">http://google.com</a>
 */
```
will render as:

See Also:
http://google.com

whereas this:
```
/**
 * See <a href="http://google.com">http://google.com</a>
 */
```
will create an in-line link:

See http://google.com
句号“.”的重要性

句号结尾，换行

同文件中逻辑代码分块

For intellij/android studio there is an amazing solution.
Start with:
//region Description
and end with:
//endregion

The shortcut for that is in the menu you can open with Command+Alt+T (Mac) or Ctrl+Alt+T (Windows)

You can also add your own line for additional visual separation if you need it. The region can be contracted and expanded at will with the +/- buttons like any function. You can also navigate between regions with Command+Alt+Period (Ctrl+Alt+Period)

Source.

Example:

//region Parceler Implementation
//---------------------------------------------------------------------------------------
@Override
public int describeContents() {
    return 0;
}

@Override
public void writeToParcel(Parcel dest, int flags) {
    dest.writeParcelable(this.die, 0);
    dest.writeParcelable(this.dieSprite, 0);
}

private DieVm(Parcel in) {
    this.die = in.readParcelable(Die.class.getClassLoader());
    this.dieSprite = in.readParcelable(Sprite.class.getClassLoader());
}

public static final Parcelable.Creator<DieVm> CREATOR = new Parcelable.Creator<DieVm>() {
    public DieVm createFromParcel(Parcel source) {
        return new DieVm(source);
    }

    public DieVm[] newArray(int size) {
        return new DieVm[size];
    }
};
//---------------------------------------------------------------------------------------
//endregion

命令生成

javadoc cmd options "-encoding utf8 -charset utf8 -doctitle HollyChatSDK -header "<b>HollyChat Android SDK </b><br>v1.0" -overview D:\mss\code\HollyChat\HollySDK\src\overview.html"

gradle

android.libraryVariants.all { variant ->
  def name = variant.buildType.name
  if (name != "release") {
    return // Skip non-release builds.
  }

  /**
  * 生成javadoc
  */
  task generateSDKApiDoc(type: Javadoc) {
    group "ApiDoc"
    description "Generates Javadoc for HollChat SDK."

    //文档标题
    title = "HollyChatSDK API Documentation (v${project.android.defaultConfig.versionName})"
    //指定源码路径
    source = android.sourceSets.main.java.srcDirs
  //        destinationDir = reporting.file(JAVA_DOC_DIR)
    //指定文档生成路径
    destinationDir = docsDir
    //        使用此方式设置classpath会导致无法找到dependence中第三方库的依赖
    //        classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
    //        classpath += project.fileTree(include: ['*.jar'], dir: 'libs')

    options {
      encoding "utf8"
      charSet 'utf8'
      windowTitle "HollChat Android SDK API"
      overview = file("src/overview.html")
      memberLevel = JavadocMemberLevel.PUBLIC
      //linkSource设置为true会把source code生成出来
      linkSource false
      author = true
      //将索引文件分成多个（默认生成一个index—all.html)
      splitIndex = true
      noDeprecated = true
      links("http://docs.oracle.com/javase/8/docs/api/")
      linksOffline "http://d.android.com/reference", "${android.sdkDirectory}/docs/reference"
    }
    options.addStringOption('Xdoclint:none', '-quiet')
    options.addStringOption('header', "<b>HollyChat Android SDK </b><br>v${project.android.defaultConfig.versionName}")

    //移除不想要添加javadoc的类（遗留问题：使用doFirst的方式设置完classpath后，会导致未exclude的类无法找到exclude的类的引用）
    exclude 'com/holly/sdk/ptt/**'
    exclude 'com/holly/sdk/util/**'
    exclude 'com/holly/sdk/data/**'
    exclude 'com/holly/sdk/model/generator/**'
    exclude '**/BuildConfig.java'
    exclude '**/R.java'
    failOnError = false
    //设定类查找路径（否则会报类找不到的错误）
    doFirst {
      //获取所有编译相关类（即便是通过dependence中通过maven库引入的依赖类）
      classpath =
        files(
          variant.javaCompileProvider.get().classpath.files,
          project.android.getBootClasspath())
    }
    //添加这一行可以解决上面的遗留问题。
    options.addStringOption("-source-path", android.sourceSets.main.java.srcDirs.join(":"))
  }
}

posted on 2023-02-08 22:42 kelisi_king 阅读(33) 评论(0) 编辑收藏举报