Introduce documentedVisibilities setting (#2270)

* 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

3 files changed, 57 insertions, 6 deletions

diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md
index 9bfcb6fb..eca68c7d 100644
--- a/docs/src/doc/docs/user_guide/cli/usage.md
+++ b/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,
diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md
index cc36329d..0b09b430 100644
--- a/docs/src/doc/docs/user_guide/gradle/usage.md
+++ b/docs/src/doc/docs/user_guide/gradle/usage.md
@@ -100,9 +100,21 @@ val dokkaHtml by getting(DokkaTask::class) {
             // 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
+            // Deprecated. Prefer using documentedVisibilities.
             includeNonPublic.set(false)
 
+            // A set of visibility modifiers that should be documented
+            // If set by user, overrides includeNonPublic. Default is PUBLIC
+            documentedVisibilities.set(
+                setOf(
+                    DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier
+                    DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility
+                )
+            )
+
             // Do not output deprecated members. Applies globally, can be overridden by packageOptions
             skipDeprecated.set(false)
 
@@ -173,11 +185,25 @@ val dokkaHtml by getting(DokkaTask::class) {
             // Repeat for multiple packageOptions
             // If multiple packages match the same matchingRegex, the longuest matchingRegex will be used
             perPackageOption {
-                matchingRegex.set("kotlin($|\\.).*") // will match kotlin and all sub-packages of it
-                // All options are optional, default values are below:
+                // 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)
+                includeNonPublic.set(false) // Deprecated, prefer using documentedVisibilities
+
+                // Visibilities that should be included in the documentation
+                // If set by user, overrides includeNonPublic. Default is PUBLIC
+                documentedVisibilities.set(
+                    setOf(
+                        DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier
+                        DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility
+                    )
+                )
             }
             // Suppress a package
             perPackageOption {
diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md
index 25ccabf0..d799396a 100644
--- a/docs/src/doc/docs/user_guide/maven/usage.md
+++ b/docs/src/doc/docs/user_guide/maven/usage.md
@@ -73,6 +73,16 @@ The available configuration options are shown below:
             <include>packages.md</include>
             <include>extra.md</include>
         </includes>
+
+        <!-- A list of visibility modifiers that should be documented -->
+        <!-- If set by user, overrides includeNonPublic. Default is PUBLIC -->
+        <documentedVisibilities>
+            <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java -->
+            <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java -->
+            <visibility>PROTECTED</visibility> <!-- Same for both kotlin and java -->
+            <visibility>INTERNAL</visibility> <!-- Kotlin-specific internal modifier -->
+            <visibility>PACKAGE</visibility> <!-- Java-specific package-private visibility (default) -->
+        </documentedVisibilities>
         
         <!-- List of sample roots -->
         <samples>
@@ -148,9 +158,22 @@ The available configuration options are shown below:
                 
                 <!-- All options are optional, default values are below: -->
                 <skipDeprecated>false</skipDeprecated>
+                
                 <!-- Emit warnings about not documented members  -->
                 <reportUndocumented>true</reportUndocumented>
+                
+                <!-- Deprecated. Prefer using documentedVisibilities -->
                 <includeNonPublic>false</includeNonPublic>
+
+                <!-- A list of visibility modifiers that should be documented -->
+                <!-- If set by user, overrides includeNonPublic. Default is PUBLIC -->
+                <documentedVisibilities>
+                    <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java -->
+                    <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java -->
+                    <visibility>PROTECTED</visibility> <!-- Same for both kotlin and java -->
+                    <visibility>INTERNAL</visibility> <!-- Kotlin-specific internal modifier -->
+                    <visibility>PACKAGE</visibility> <!-- Java-specific package-private visibility (default) -->
+                </documentedVisibilities>
             </packageOptions>
         </perPackageOptions>