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 -nodeprecatedhttps://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.comwhereas this:
/** * See <a href="http://google.com">http://google.com</a> */will create an in-line link:
-
句号“.”的重要性
句号结尾，换行
-
For intellij/android studio there is an amazing solution.
Start with:
//region Description
and end with:
//endregionThe 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)
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())
}
}
}