From bfd41ce2a0d43419a671961c19b7d755cffdcfc8 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 23 Dec 2021 14:32:18 +0300 Subject: 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 --- docs/src/doc/docs/user_guide/cli/usage.md | 6 +++-- docs/src/doc/docs/user_guide/gradle/usage.md | 34 ++++++++++++++++++++++++---- docs/src/doc/docs/user_guide/maven/usage.md | 23 +++++++++++++++++++ 3 files changed, 57 insertions(+), 6 deletions(-) (limited to 'docs/src') 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 `=[#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: packages.md extra.md + + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + @@ -148,9 +158,22 @@ The available configuration options are shown below: false + true + + false + + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + -- cgit