Introduce documentedVisibilities setting

core/api/core.api

@@ -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;
@@ -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;
@@ -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;
 }
@@ -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;
@@ -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
@@ -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;
@@ -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;

core/src/main/kotlin/DokkaBootstrapImpl.kt

@@ -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

core/src/main/kotlin/configuration.kt

@@ -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
@@ -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
@@ -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 {
@@ -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 {

core/src/main/kotlin/defaultConfiguration.kt

@@ -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(
@@ -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
 
 

core/test-api/api/test-api.api

@@ -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;
@@ -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

core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt

@@ -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,
@@ -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,
@@ -137,6 +140,7 @@ val defaultSourceSet = DokkaSourceSetImpl(
     samples = emptySet(),
     includes = emptySet(),
     includeNonPublic = false,
+    documentedVisibilities = DokkaDefaults.documentedVisibilities,
     reportUndocumented = false,
     skipEmptyPackages = true,
     skipDeprecated = false,

docs/src/doc/docs/user_guide/cli/usage.md

@@ -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
@@ -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,