Skip to content

Commit

Permalink
Introduce documentedVisibilities setting (Kotlin#2270)
Browse files Browse the repository at this point in the history 
* Introduce `documentedVisibilities` setting

* Remove hardcoded doc generation for Visibility.PUBLIC, correct tests

* Add maven, gradle and cli integration tests for documentedVisibilities

* Fix maven plugin configuration overriding the default value

* Remove test debug prints

* Correct an inconsistency with default values and leave a comment of intentions

* Add a test for visibility of private setter
  • Loading branch information
@IgnatBeresnev @owengray-google
IgnatBeresnev authored and owengray-google committed Dec 29, 2021
1 parent b9394f8 commit aa37c4b
Show file tree
Hide file tree
Showing 46 changed files with 1,185 additions and 45 deletions.
36 changes: 29 additions & 7 deletions core/api/core.api
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ public abstract interface class org/jetbrains/dokka/DokkaConfiguration$DokkaSour
public abstract fun getClasspath ()Ljava/util/List;
public abstract fun getDependentSourceSets ()Ljava/util/Set;
public abstract fun getDisplayName ()Ljava/lang/String;
public abstract fun getDocumentedVisibilities ()Ljava/util/Set;
public abstract fun getExternalDocumentationLinks ()Ljava/util/Set;
public abstract fun getIncludeNonPublic ()Z
public abstract fun getIncludes ()Ljava/util/Set;
Expand Down Expand Up @@ -117,6 +118,7 @@ public final class org/jetbrains/dokka/DokkaConfiguration$ExternalDocumentationL
}

public abstract interface class org/jetbrains/dokka/DokkaConfiguration$PackageOptions : java/io/Serializable {
public abstract fun getDocumentedVisibilities ()Ljava/util/Set;
public abstract fun getIncludeNonPublic ()Z
public abstract fun getMatchingRegex ()Ljava/lang/String;
public abstract fun getReportUndocumented ()Ljava/lang/Boolean;
Expand All @@ -143,6 +145,21 @@ public abstract interface class org/jetbrains/dokka/DokkaConfiguration$SourceLin
public abstract fun getRemoteUrl ()Ljava/net/URL;
}

public final class org/jetbrains/dokka/DokkaConfiguration$Visibility : java/lang/Enum {
public static final field Companion Lorg/jetbrains/dokka/DokkaConfiguration$Visibility$Companion;
public static final field INTERNAL Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
public static final field PACKAGE Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
public static final field PRIVATE Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
public static final field PROTECTED Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
public static final field PUBLIC Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
public static fun values ()[Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
}

public final class org/jetbrains/dokka/DokkaConfiguration$Visibility$Companion {
public final fun fromString (Ljava/lang/String;)Lorg/jetbrains/dokka/DokkaConfiguration$Visibility;
}

public abstract interface class org/jetbrains/dokka/DokkaConfigurationBuilder {
public abstract fun build ()Ljava/lang/Object;
}
Expand Down Expand Up @@ -206,6 +223,7 @@ public final class org/jetbrains/dokka/DokkaDefaults {
public static final field suppressObviousFunctions Z
public final fun getAnalysisPlatform ()Lorg/jetbrains/dokka/Platform;
public final fun getCacheRoot ()Ljava/io/File;
public final fun getDocumentedVisibilities ()Ljava/util/Set;
public final fun getModuleName ()Ljava/lang/String;
public final fun getModuleVersion ()Ljava/lang/String;
public final fun getOutputDir ()Ljava/io/File;
Expand Down Expand Up @@ -254,8 +272,8 @@ public final class org/jetbrains/dokka/DokkaSourceSetID : java/io/Serializable {
}

public final class org/jetbrains/dokka/DokkaSourceSetImpl : org/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet {
public fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;)V
public synthetic fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;)V
public synthetic fun <init> (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun component1 ()Ljava/lang/String;
public final fun component10 ()Z
public final fun component11 ()Z
Expand All @@ -270,21 +288,23 @@ public final class org/jetbrains/dokka/DokkaSourceSetImpl : org/jetbrains/dokka/
public final fun component2 ()Lorg/jetbrains/dokka/DokkaSourceSetID;
public final fun component20 ()Ljava/util/Set;
public final fun component21 ()Lorg/jetbrains/dokka/Platform;
public final fun component22 ()Ljava/util/Set;
public final fun component3 ()Ljava/util/List;
public final fun component4 ()Ljava/util/Set;
public final fun component5 ()Ljava/util/Set;
public final fun component6 ()Ljava/util/Set;
public final fun component7 ()Ljava/util/Set;
public final fun component8 ()Z
public final fun component9 ()Z
public final fun copy (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;)Lorg/jetbrains/dokka/DokkaSourceSetImpl;
public static synthetic fun copy$default (Lorg/jetbrains/dokka/DokkaSourceSetImpl;Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;ILjava/lang/Object;)Lorg/jetbrains/dokka/DokkaSourceSetImpl;
public final fun copy (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;)Lorg/jetbrains/dokka/DokkaSourceSetImpl;
public static synthetic fun copy$default (Lorg/jetbrains/dokka/DokkaSourceSetImpl;Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;ILjava/lang/Object;)Lorg/jetbrains/dokka/DokkaSourceSetImpl;
public fun equals (Ljava/lang/Object;)Z
public fun getAnalysisPlatform ()Lorg/jetbrains/dokka/Platform;
public fun getApiVersion ()Ljava/lang/String;
public fun getClasspath ()Ljava/util/List;
public fun getDependentSourceSets ()Ljava/util/Set;
public fun getDisplayName ()Ljava/lang/String;
public fun getDocumentedVisibilities ()Ljava/util/Set;
public fun getExternalDocumentationLinks ()Ljava/util/Set;
public fun getIncludeNonPublic ()Z
public fun getIncludes ()Ljava/util/Set;
Expand Down Expand Up @@ -324,15 +344,17 @@ public final class org/jetbrains/dokka/ExternalDocumentationLinkImpl : org/jetbr
}

public final class org/jetbrains/dokka/PackageOptionsImpl : org/jetbrains/dokka/DokkaConfiguration$PackageOptions {
public fun <init> (Ljava/lang/String;ZLjava/lang/Boolean;ZZ)V
public fun <init> (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;)V
public final fun component1 ()Ljava/lang/String;
public final fun component2 ()Z
public final fun component3 ()Ljava/lang/Boolean;
public final fun component4 ()Z
public final fun component5 ()Z
public final fun copy (Ljava/lang/String;ZLjava/lang/Boolean;ZZ)Lorg/jetbrains/dokka/PackageOptionsImpl;
public static synthetic fun copy$default (Lorg/jetbrains/dokka/PackageOptionsImpl;Ljava/lang/String;ZLjava/lang/Boolean;ZZILjava/lang/Object;)Lorg/jetbrains/dokka/PackageOptionsImpl;
public final fun component6 ()Ljava/util/Set;
public final fun copy (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;)Lorg/jetbrains/dokka/PackageOptionsImpl;
public static synthetic fun copy$default (Lorg/jetbrains/dokka/PackageOptionsImpl;Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;ILjava/lang/Object;)Lorg/jetbrains/dokka/PackageOptionsImpl;
public fun equals (Ljava/lang/Object;)Z
public fun getDocumentedVisibilities ()Ljava/util/Set;
public fun getIncludeNonPublic ()Z
public fun getMatchingRegex ()Ljava/lang/String;
public fun getReportUndocumented ()Ljava/lang/Boolean;
Expand Down
7 changes: 7 additions & 0 deletions core/src/main/kotlin/DokkaBootstrapImpl.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,16 @@ fun parsePerPackageOptions(args: List<String>): List<PackageOptions> = args.map
val suppress = options.find { it.endsWith("suppress") }?.startsWith("+")
?: DokkaDefaults.suppress

val documentedVisibilities = options
.filter { it.matches(Regex("\\+visibility:.+")) } // matches '+visibility:' with at least one symbol after the semicolon
.map { DokkaConfiguration.Visibility.fromString(it.split(":")[1]) }
.toSet()
.ifEmpty { DokkaDefaults.documentedVisibilities }

PackageOptionsImpl(
matchingRegex,
includeNonPublic = privateApi,
documentedVisibilities = documentedVisibilities,
reportUndocumented = reportUndocumented,
skipDeprecated = !deprecated,
suppress = suppress
Expand Down
36 changes: 36 additions & 0 deletions core/src/main/kotlin/configuration.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ object DokkaDefaults {
const val delayTemplateSubstitution: Boolean = false

const val includeNonPublic: Boolean = false
val documentedVisibilities: Set<DokkaConfiguration.Visibility> = setOf(DokkaConfiguration.Visibility.PUBLIC)
const val reportUndocumented: Boolean = false
const val skipEmptyPackages: Boolean = true
const val skipDeprecated: Boolean = false
Expand Down Expand Up @@ -122,6 +123,7 @@ interface DokkaConfiguration : Serializable {
val dependentSourceSets: Set<DokkaSourceSetID>
val samples: Set<File>
val includes: Set<File>
@Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities")
val includeNonPublic: Boolean
val reportUndocumented: Boolean
val skipEmptyPackages: Boolean
Expand All @@ -136,6 +138,38 @@ interface DokkaConfiguration : Serializable {
val noJdkLink: Boolean
val suppressedFiles: Set<File>
val analysisPlatform: Platform
val documentedVisibilities: Set<Visibility>
}

enum class Visibility {
/**
* `public` modifier for Java, default visibility for Kotlin
*/
PUBLIC,

/**
* `private` modifier for both Kotlin and Java
*/
PRIVATE,

/**
* `protected` modifier for both Kotlin and Java
*/
PROTECTED,

/**
* Kotlin-specific `internal` modifier
*/
INTERNAL,

/**
* Java-specific package-private visibility (no modifier)
*/
PACKAGE;

companion object {
fun fromString(value: String) = valueOf(value.toUpperCase())
}
}

interface SourceLinkDefinition : Serializable {
Expand All @@ -153,10 +187,12 @@ interface DokkaConfiguration : Serializable {

interface PackageOptions : Serializable {
val matchingRegex: String
@Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities")
val includeNonPublic: Boolean
val reportUndocumented: Boolean?
val skipDeprecated: Boolean
val suppress: Boolean
val documentedVisibilities: Set<Visibility>
}

interface ExternalDocumentationLink : Serializable {
Expand Down
2 changes: 2 additions & 0 deletions core/src/main/kotlin/defaultConfiguration.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ data class DokkaSourceSetImpl(
override val noJdkLink: Boolean = DokkaDefaults.noJdkLink,
override val suppressedFiles: Set<File> = emptySet(),
override val analysisPlatform: Platform = DokkaDefaults.analysisPlatform,
override val documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities,
) : DokkaSourceSet

data class DokkaModuleDescriptionImpl(
Expand Down Expand Up @@ -81,6 +82,7 @@ data class PackageOptionsImpl(
override val reportUndocumented: Boolean?,
override val skipDeprecated: Boolean,
override val suppress: Boolean,
override val documentedVisibilities: Set<DokkaConfiguration.Visibility>,
) : DokkaConfiguration.PackageOptions


Expand Down
6 changes: 4 additions & 2 deletions core/test-api/api/test-api.api
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,14 +83,15 @@ public abstract interface annotation class testApi/testRunner/DokkaConfiguration
}

public final class testApi/testRunner/DokkaSourceSetBuilder {
public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V
public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZLjava/util/Set;ZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V
public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZLjava/util/Set;ZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
public final fun build ()Lorg/jetbrains/dokka/DokkaSourceSetImpl;
public final fun getAnalysisPlatform ()Ljava/lang/String;
public final fun getApiVersion ()Ljava/lang/String;
public final fun getClasspath ()Ljava/util/List;
public final fun getDependentSourceSets ()Ljava/util/Set;
public final fun getDisplayName ()Ljava/lang/String;
public final fun getDocumentedVisibilities ()Ljava/util/Set;
public final fun getExternalDocumentationLinks ()Ljava/util/List;
public final fun getIncludeNonPublic ()Z
public final fun getIncludes ()Ljava/util/List;
Expand All @@ -112,6 +113,7 @@ public final class testApi/testRunner/DokkaSourceSetBuilder {
public final fun setClasspath (Ljava/util/List;)V
public final fun setDependentSourceSets (Ljava/util/Set;)V
public final fun setDisplayName (Ljava/lang/String;)V
public final fun setDocumentedVisibilities (Ljava/util/Set;)V
public final fun setExternalDocumentationLinks (Ljava/util/List;)V
public final fun setIncludeNonPublic (Z)V
public final fun setIncludes (Ljava/util/List;)V
Expand Down
4 changes: 4 additions & 0 deletions core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,9 @@ class DokkaSourceSetBuilder(
var dependentSourceSets: Set<DokkaSourceSetID> = emptySet(),
var samples: List<String> = emptyList(),
var includes: List<String> = emptyList(),
@Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities")
var includeNonPublic: Boolean = false,
var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities,
var reportUndocumented: Boolean = false,
var skipEmptyPackages: Boolean = false,
var skipDeprecated: Boolean = false,
Expand All @@ -112,6 +114,7 @@ class DokkaSourceSetBuilder(
samples = samples.map(::File).toSet(),
includes = includes.map(::File).toSet(),
includeNonPublic = includeNonPublic,
documentedVisibilities = documentedVisibilities,
reportUndocumented = reportUndocumented,
skipEmptyPackages = skipEmptyPackages,
skipDeprecated = skipDeprecated,
Expand All @@ -137,6 +140,7 @@ val defaultSourceSet = DokkaSourceSetImpl(
samples = emptySet(),
includes = emptySet(),
includeNonPublic = false,
documentedVisibilities = DokkaDefaults.documentedVisibilities,
reportUndocumented = false,
skipEmptyPackages = true,
skipDeprecated = false,
Expand Down
6 changes: 4 additions & 2 deletions docs/src/doc/docs/user_guide/cli/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,12 @@ Dokka supports the following command line arguments:
* `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;`
* `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) separated by `;`
* `-includes` - list of files containing the documentation for the module and individual packages separated by `;`
* `-includeNonPublic` - include protected and private code
* `-includeNonPublic` - **Deprecated**, prefer using `documentedVisibilities`. Include protected and private code
* `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Overrides `includeNonPublic`. Default is `PUBLIC`. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private)
* `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation
* `-reportUndocumented` - warn about undocumented members
* `-noSkipEmptyPackages` - create index pages for empty packages
* `-packageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;matchingRegex, ...`, separated by `;`
* `-perPackageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;+visibility:PRIVATE;matchingRegex, ...`, separated by `;`
* `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;`
* `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `<path>=<url>[#lineSuffix]`
* `-noStdlibLink` - disable linking to online kotlin-stdlib documentation
Expand Down Expand Up @@ -104,6 +105,7 @@ The content of JSON file ```dokkaConfiguration.json```:
"Module.md"
],
"includeNonPublic": false,
"documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
"reportUndocumented": false,
"skipEmptyPackages": true,
"skipDeprecated": false,
Expand Down
Loading

0 comments on commit aa37c4b

Please sign in to comment.