Dokka로 프로젝트 문서화하기

이번 포스팅에서는 Dokka로 프로젝트를 문서화하는 법에 대해 알아보도록 하겠습니다.

Dokka는 코틀린과 자바로 작성된 프로젝트의 코드를 분석해서 문서화해주는 플러그인인데요 Java의 Javadoc과 Kotlin의 Kdoc 구조를 분석할 수 있습니다. 문서는 Javadoc, HTML 형식으로 출력할 수 있습니다.

그러면 안드로이드 스튜디오의 예제 프로젝트에 Dokka를 적용해 보도록 하겠습니다. 우선 New project > Login Activity를 선택합니다. 이 프로젝트는 약간의 구조화가 되어 있고 클래스마다 주석이 달려있기 때문에 Dokka의 예제로 사용하기 좋아보인다는 이유로 당첨되었습니다.

다음은 build.gradle에 플러그인을 추가합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// Top-level build.gradle
plugins {
    id "org.jetbrains.dokka" version "1.7.10"
}

// App-level build.gradle
plugins {
    id "org.jetbrains.dokka"
}

android {
    ...
    dokkaHtml.configure {
        dokkaSourceSets {
            named("main") {
                noAndroidSdkLink.set(false)
            }
        }
    }
}

플러그인을 설치한 뒤 다음 커맨드를 실행시키면 문서가 생성됩니다.

1

./gradlew dokka${format}

Html 문서를 만들고 싶은 경우 ./gradlew dokkaHtml, Javadoc 문서를 작성하고 싶은 경우 ./gradlew dokkaJavadoc을 실행시키면 됩니다. 여기서는 두 타입의 문서를 모두 작성해 보겠습니다. 커맨드를 실행하면 app > build > dokka 폴더에 파일이 생성되기 때문에 index.html을 브라우저에서 실행시키면 됩니다. 그러면 안드로이드 프로젝트 구조에 따라 Html이 보이며 클래스에 달아준 주석의 내용이 같이 표시되게 됩니다.

여기서는 noAndroidSdkLink.set(false) 옵션을 적용해서 Dokka 문서가 Android developers의 문서와 연결되지 않도록 했는데 이 외에도 다음과 같이 많은 옵션이 있습니다.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130


import org.jetbrains.dokka.gradle.DokkaTask

val dokkaHtml by getting(DokkaTask::class) {
    outputDirectory.set(buildDir.resolve("dokka"))

    // Set module name displayed in the final output
    moduleName.set("moduleName")

    // Use default or set to custom path to cache directory
    // to enable package-list caching
    // When this is set to default, caches are stored in $USER_HOME/.cache/dokka
    cacheRoot.set(file("default"))

    // Suppress obvious functions like default toString or equals. Defaults to true
    suppressObviousFunctions.set(false)

    // Suppress all inherited members that were not overriden in a given class. 
    // Eg. using it you can suppress toString or equals functions but you can't suppress componentN or copy on data class. To do that use with suppressObviousFunctions
    // Defaults to false
    suppressInheritedMembers.set(true)

    // Used to prevent resolving package-lists online. When this option is set to true, only local files are resolved  
    offlineMode.set(false)

    dokkaSourceSets {
        configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`

            // Used when configuring source sets manually for declaring which source sets this one depends on
            dependsOn("otherSourceSetName")

            // Used to remove a source set from documentation, test source sets are suppressed by default  
            suppress.set(false)

            // Use to include or exclude non public members 
            includeNonPublic.set(false)

            // Do not output deprecated members. Applies globally, can be overridden by packageOptions
            skipDeprecated.set(false)

            // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
            reportUndocumented.set(true)

            // Do not create index pages for empty packages
            skipEmptyPackages.set(true)

            // This name will be shown in the final output
            displayName.set("JVM")

            // Platform used for code analysis. See the "Platforms" section of this readme
            platform.set(org.jetbrains.dokka.Platform.jvm)

            // Property used for manual addition of files to the classpath
            // This property does not override the classpath collected automatically but appends to it
            classpath.from(file("libs/dependency.jar"))

            // List of files with module and package documentation
            // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
            includes.from("packages.md", "extra.md")

            // List of files or directories containing sample code (referenced with @sample tags)
            samples.from("samples/basic.kt", "samples/advanced.kt")

            // By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them
            // Repeat for multiple sourceRoots
            sourceRoots.from(file("src"))

            // Specifies the location of the project source code on the Web.
            // If provided, Dokka generates "source" links for each declaration.
            // Repeat for multiple mappings
            sourceLink {
                // Unix based directory relative path to the root of the project (where you execute gradle respectively). 
                localDirectory.set(file("src/main/kotlin"))

                // URL showing where the source code can be accessed through the web browser
                remoteUrl.set(java.net.URL(
                    "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"))
                // Suffix which is used to append the line number to the URL. Use #L for GitHub
                remoteLineSuffix.set("#L")
            }

            // Used for linking to JDK documentation
            jdkVersion.set(8)

            // Disable linking to online kotlin-stdlib documentation
            noStdlibLink.set(false)

            // Disable linking to online JDK documentation
            noJdkLink.set(false)

            // Disable linking to online Android documentation (only applicable for Android projects)
            noAndroidSdkLink.set(false)

            // Allows linking to documentation of the project"s dependencies (generated with Javadoc or Dokka)
            // Repeat for multiple links
            externalDocumentationLink {
                // Root URL of the generated documentation to link with. The trailing slash is required!
                url.set(URL("https://example.com/docs/"))

                // If package-list file is located in non-standard location
                // packageListUrl = URL("file:///home/user/localdocs/package-list")
            }

            // Allows to customize documentation generation options on a per-package basis
            // Repeat for multiple packageOptions
            // If multiple packages match the same matchingRegex, the longuest matchingRegex will be used
            perPackageOption {
                // will match kotlin and all sub-packages of it
                matchingRegex.set("kotlin($|\\.).*") 

                // All options are optional
                skipDeprecated.set(false)
                reportUndocumented.set(true) // Emit warnings about not documented members 
                includeNonPublic.set(false)
            }
            // Suppress a package
            perPackageOption {
                matchingRegex.set(""".*\.internal.*""") // will match all .internal packages and sub-packages 
                suppress.set(true)
            }

            // Include generated files in documentation
            // By default Dokka will omit all files in folder named generated that is a child of buildDir
            suppressGeneratedFiles.set(false)
        }
        // Configures a plugin separately from the global configuration
        pluginConfiguration<PluginClass, ConfigurationClass>{
            // values
        }
    }
}

이렇게 해서 Dokka로 프로젝트를 문서화하는 법에 대해 알아보았습니다.

GitHub/cliearl