Kotlin -- 文档生成工具Dokka

作者：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导出的文档格式比较好。格式参考文章

万水千山总是情，麻烦手下别留情。
如若讲得有不妥，文末留言告知我，
如若觉得还可以，收藏点赞要一起。
opLW原创七言律诗，转载请注明出处