作者:opLW
Kotlin文档撰写注意点:Kotlin – 一文详解Kotlin文档
1.Dokka制作文档的步骤
-
1.1 在project的build.gradle中添加仓库和依赖
buildscript { repositories { maven { url 'http://maven.aliyun.com/nexus/content/groups/public/' } // 或者jcenter() ...... } dependencies { ...... classpath 'org.jetbrains.dokka:dokka-gradle-plugin:0.10.1' } }
-
1.2 在app的build.gradle中添加插件以及配置dokka参数
apply plugin: 'org.jetbrains.dokka' android { ...... dokka { outputFormat = 'javadoc' outputDirectory = "$buildDir/dokka" configuration { // Do not output deprecated members skipDeprecated = true // Emit warnings about not documented members. reportUndocumented = true // Do not create index pages for empty packages skipEmptyPackages = true noJdkLink = true noStdlibLink = true noAndroidSdkLink = true } } } dependencies { ...... }
前两步做完
sync
文件 -
1.3 运行dokka任务
- 打开右侧的
Gradle
窗口,然后通过MyProject --> app --> Tasks --> documentation --> dokka
找到该任务,双击运行任务 - 在
terminal
窗口中输入gradlew dokka
运行任务。
- 打开右侧的
-
1.4 查看生成的文档
通过MyProject --> app --> build --> dokka --> com
找到index.html
文件,右键选择Open in Browser
在浏览器中打开。 -
参考文章 github - dokka、stackoverflow - Dokka plugin not found in Android studio 3
2.遇到的问题
- 2.1 运行dokka任务时出现错误:Exception while loading package-list from ExternalDocumentationLinkImp
- 出现上述错误的主要原因是网络问题, Kotlin社区的一篇文章 详细讲解了如何配置参数。
- 如果没有VPN、无法手动下载package-list,则参考
Dokka的issues中的做法,为dokka的配置加入如下参数:(最终配置如上)noJdkLink = true noStdlibLink = true noAndroidSdkLink = true
- 2.2 Dokka中outputFormat参数的选择
- javadoc格式
- html格式
- 上述可见,javadoc导出的文档格式比较好。格式参考文章
- javadoc格式
万水千山总是情,麻烦手下别留情。
如若讲得有不妥,文末留言告知我,
如若觉得还可以,收藏点赞要一起。
opLW原创七言律诗,转载请注明出处