Add option to suppress annotated declarations

docs/topics/dokka-gradle-configuration-options.md

@@ -391,6 +391,12 @@ dokka {
         </p>
         <p>Default: <code>true</code></p>
     </def>
+    <def title="suppressedAnnotations">
+        <p>A set of annotation fully qualified names (FQNs) to suppress declarations annotated with.</p>
+        <p>
+            Any declaration annotated with one of these annotations is excluded from the generated documentation.
+        </p>
+    </def>
     <def title="jdkVersion">
         <p>The JDK version to use when generating external documentation links for Java types.</p>
         <p>

docs/topics/runners/dokka-cli.md

@@ -202,6 +202,7 @@ Short summary:
 | `noStdlibLink`               | Whether to generate links to the Kotlin standard library.                                                                                                                      | 
 | `noJdkLink`                  | Whether to generate links to JDK Javadocs.                                                                                                                                     | 
 | `suppressedFiles`            | Paths to files to be suppressed. Accepts multiple paths separated by semicolons.                                                                                               |
+| `suppressedAnnotations`      | Annotation fully qualified names (FQNs) to suppress declarations annotated with. Accepts multiple values separated by semicolons.                                              |
 | `analysisPlatform`           | Platform used for setting up analysis.                                                                                                                                         |
 | `perPackageOptions`          | List of package source set configurations in format `matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;...`. Accepts multiple values separated by semicolons. |
 | `externalDocumentationLinks` | External documentation links in format `{url}^{packageListUrl}`. Accepts multiple values separated by `^^`.                                                                    |
@@ -535,6 +536,12 @@ How to configure Kotlin
     <def title="suppressedFiles">
         <p>The files to be suppressed when generating documentation.</p>
     </def>
+    <def title="suppressedAnnotations">
+        <p>A list of annotation fully qualified names (FQNs) to suppress declarations annotated with.</p>
+        <p>
+            Any declaration annotated with one of these annotations is excluded from the generated documentation.
+        </p>
+    </def>
     <def title="sourceLinks">
         <p>A set of parameters for source links that is applied only for this source set.</p>
         <p>For a list of possible options, see <a href="#source-link-configuration">source link configuration</a>.</p>
@@ -724,6 +731,9 @@ Below you can see all possible configuration options applied at the same time.
   "suppressObviousFunctions": true,
   "suppressInheritedMembers": false,
   "offlineMode": false,
+  "suppressedAnnotations": [
+    "com.example.SuppressMe"
+  ],
   "sourceLinks": [
     {
       "localDirectory": "src/main/kotlin",
@@ -789,6 +799,9 @@ Below you can see all possible configuration options applied at the same time.
       "suppressedFiles": [
         "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
       ],
+      "suppressedAnnotations": [
+        "com.example.SuppressMe"
+      ],
       "sourceLinks": [
         {
           "localDirectory": "src/main/kotlin",

docs/topics/runners/dokka-maven.md

@@ -188,6 +188,9 @@ with [all configuration options](#complete-configuration) applied at the bottom
             <file>/path/to/dir</file>
             <file>/path/to/file</file>
         </suppressedFiles>
+        <suppressedAnnotations>
+            <annotation>com.example.SuppressMe</annotation>
+        </suppressedAnnotations>
         <jdkVersion>8</jdkVersion>
         <languageVersion>1.7</languageVersion>
         <apiVersion>1.7</apiVersion>
@@ -324,6 +327,12 @@ with [all configuration options](#complete-configuration) applied at the bottom
             are not documented.
         </p>
     </def>
+    <def title="suppressedAnnotations">
+        <p>A list of annotation fully qualified names (FQNs) to suppress declarations annotated with.</p>
+        <p>
+            Any declaration annotated with one of these annotations is excluded from the generated documentation.
+        </p>
+    </def>
     <def title="jdkVersion">
         <p>The JDK version to use when generating external documentation links for Java types.</p>
         <p>

dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api

@@ -300,6 +300,7 @@ public abstract class org/jetbrains/dokka/gradle/engine/parameters/DokkaSourceSe
 	public abstract fun getSourceSetScope ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppress ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppressGeneratedFiles ()Lorg/gradle/api/provider/Property;
+	public abstract fun getSuppressedAnnotations ()Lorg/gradle/api/provider/SetProperty;
 	public abstract fun getSuppressedFiles ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	public final fun perPackageOption (Lorg/gradle/api/Action;)V
 	public final fun sourceLink (Lorg/gradle/api/Action;)V

dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt

@@ -281,6 +281,13 @@ constructor(
     @get:Input
     abstract val suppressGeneratedFiles: Property<Boolean>
 
+    /**
+     * A set of annotation fully qualified names (FQNs) to suppress declarations annotated with.
+     * Any declaration annotated with one of these annotations will be excluded from the generated documentation.
+     */
+    @get:Input
+    abstract val suppressedAnnotations: SetProperty<String>
+
     /**
      * Whether to generate external documentation links that lead to API reference documentation for
      * Kotlin's standard library when declarations from it are used.

dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaSourceSetBuilder.kt

@@ -73,6 +73,7 @@ internal object DokkaSourceSetBuilder {
             skipEmptyPackages = spec.skipEmptyPackages.get(),
             sourceLinks = spec.sourceLinks.mapToSet { build(it) },
             sourceSetID = build(spec.sourceSetId.get()),
+            suppressedAnnotations = spec.suppressedAnnotations.get(),
 
             // files
             classpath = spec.classpath.files.toList(),

dokka-runners/runner-cli/api/runner-cli.api

@@ -69,6 +69,7 @@ public final class org/jetbrains/dokka/GlobalArguments : org/jetbrains/dokka/Dok
 	public final fun getGlobalLinks ()Ljava/util/List;
 	public final fun getGlobalPackageOptions ()Ljava/util/List;
 	public final fun getGlobalSrcLink ()Ljava/util/List;
+	public final fun getGlobalSuppressedAnnotations ()Ljava/util/List;
 	public final fun getHelpSourceSet ()Ljava/lang/Object;
 	public fun getIncludes ()Ljava/util/Set;
 	public final fun getJson ()Ljava/lang/String;

dokka-runners/runner-cli/src/main/kotlin/org/jetbrains/dokka/GlobalArguments.kt

@@ -110,6 +110,13 @@ public class GlobalArguments(args: Array<String>) : DokkaConfiguration {
                 "Accepts multiple paths separated by semicolons"
     ).delimiter(";")
 
+    public val globalSuppressedAnnotations: List<String> by parser.option(
+        ArgType.String,
+        fullName = "globalSuppressedAnnotations",
+        description = "Global list of annotation FQNs to suppress declarations annotated with. " +
+                "Accepts multiple values separated by semicolons"
+    ).delimiter(";")
+
     public val helpSourceSet: Any? by parser.option(
         ArgTypeHelpSourceSet(_moduleName),
         description = "Prints help for nested -sourceSet configuration"
@@ -164,5 +171,9 @@ public class GlobalArguments(args: Array<String>) : DokkaConfiguration {
         sourceSets.forEach {
             it.externalDocumentationLinks.cast<MutableSet<DokkaConfiguration.ExternalDocumentationLink>>().addAll(defaultLinks(it))
         }
+
+        sourceSets.forEach {
+            it.suppressedAnnotations.cast<MutableSet<String>>().addAll(globalSuppressedAnnotations)
+        }
     }
 }

dokka-runners/runner-cli/src/main/kotlin/org/jetbrains/dokka/SourceSetArgumentsParser.kt

@@ -107,6 +107,11 @@ internal fun parseSourceSet(moduleName: String, args: Array<String>): DokkaConfi
         description = "Paths to files to be suppressed. Accepts multiple paths separated by semicolons."
     ).delimiter(";")
 
+    val suppressedAnnotations by parser.option(
+        ArgType.String,
+        description = "List of annotation FQNs to suppress declarations annotated with. Accepts multiple values separated by semicolons."
+    ).delimiter(";")
+
     val analysisPlatform: Platform by parser.option(
         ArgTypePlatform,
         description = "Platform used for setting up analysis"
@@ -159,6 +164,8 @@ internal fun parseSourceSet(moduleName: String, args: Array<String>): DokkaConfi
         override val noStdlibLink = noStdlibLink
         override val noJdkLink = noJdkLink
         override val suppressedFiles = suppressedFiles.toMutableSet()
+        override val suppressedAnnotations: Set<String> = suppressedAnnotations.toSet()
+            .ifEmpty { DokkaDefaults.suppressedAnnotations }.toMutableSet()
         override val documentedVisibilities: Set<DokkaConfiguration.Visibility> = documentedVisibilities.toSet()
             .ifEmpty { DokkaDefaults.documentedVisibilities }
 

dokka-runners/runner-maven-plugin/api/runner-maven-plugin.api

@@ -32,6 +32,7 @@ public abstract class org/jetbrains/dokka/maven/AbstractDokkaMojo : org/apache/m
 	public final fun getSourceSetName ()Ljava/lang/String;
 	public final fun getSuppressInheritedMembers ()Z
 	public final fun getSuppressObviousFunctions ()Z
+	public final fun getSuppressedAnnotations ()Ljava/util/List;
 	public final fun getSuppressedFiles ()Ljava/util/List;
 	public final fun setApiVersion (Ljava/lang/String;)V
 	public final fun setCacheRoot (Ljava/lang/String;)V
@@ -63,6 +64,7 @@ public abstract class org/jetbrains/dokka/maven/AbstractDokkaMojo : org/apache/m
 	public final fun setSourceSetName (Ljava/lang/String;)V
 	public final fun setSuppressInheritedMembers (Z)V
 	public final fun setSuppressObviousFunctions (Z)V
+	public final fun setSuppressedAnnotations (Ljava/util/List;)V
 	public final fun setSuppressedFiles (Ljava/util/List;)V
 }
 

dokka-runners/runner-maven-plugin/src/main/kotlin/org/jetbrains/dokka/maven/DokkaMojo.kt

@@ -261,6 +261,13 @@ public abstract class AbstractDokkaMojo(
     @Parameter
     public var suppressedFiles: List<String> = emptyList()
 
+    /**
+     * A list of annotation fully qualified names (FQNs) to suppress declarations annotated with.
+     * Any declaration annotated with one of these annotations will be excluded from the generated documentation.
+     */
+    @Parameter
+    public var suppressedAnnotations: List<String> = emptyList()
+
     /**
      * Set of visibility modifiers that should be documented.
      *
@@ -407,6 +414,7 @@ public abstract class AbstractDokkaMojo(
             noStdlibLink = noStdlibLink,
             noJdkLink = noJdkLink,
             suppressedFiles = suppressedFiles.map(::File).toSet(),
+            suppressedAnnotations = suppressedAnnotations.toSet(),
             analysisPlatform = if (platform.isNotEmpty()) Platform.fromString(platform) else Platform.DEFAULT,
         ).let {
             it.copy(

dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationMapper.kt

@@ -176,6 +176,8 @@ private fun TestDokkaSourceSet.toDokkaSourceSet(relativeToDir: File): DokkaConfi
             get() = throw NotImplementedError("Not expected to be used by analysis modules")
         override val suppressedFiles: Set<File>
             get() = throw NotImplementedError("Not expected to be used by analysis modules")
+        override val suppressedAnnotations: Set<String>
+            get() = throw NotImplementedError("Not expected to be used by analysis modules")
         override val documentedVisibilities: Set<DokkaConfiguration.Visibility>
             get() = throw NotImplementedError("Not expected to be used by analysis modules")
     }

dokka-subprojects/core-test-api/api/dokka-test-api.api

@@ -87,8 +87,8 @@ 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;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 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;Ljava/util/Set;)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;Ljava/util/Set;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;
@@ -111,6 +111,7 @@ public final class testApi/testRunner/DokkaSourceSetBuilder {
 	public final fun getSkipEmptyPackages ()Z
 	public final fun getSourceLinks ()Ljava/util/List;
 	public final fun getSourceRoots ()Ljava/util/List;
+	public final fun getSuppressedAnnotations ()Ljava/util/Set;
 	public final fun getSuppressedFiles ()Ljava/util/List;
 	public final fun setAnalysisPlatform (Ljava/lang/String;)V
 	public final fun setApiVersion (Ljava/lang/String;)V
@@ -133,6 +134,7 @@ public final class testApi/testRunner/DokkaSourceSetBuilder {
 	public final fun setSkipEmptyPackages (Z)V
 	public final fun setSourceLinks (Ljava/util/List;)V
 	public final fun setSourceRoots (Ljava/util/List;)V
+	public final fun setSuppressedAnnotations (Ljava/util/Set;)V
 	public final fun setSuppressedFiles (Ljava/util/List;)V
 }
 

dokka-subprojects/core-test-api/src/main/kotlin/org/jetbrains/dokka/testApi/testRunner/TestDokkaConfigurationBuilder.kt

@@ -111,7 +111,8 @@ public class DokkaSourceSetBuilder(
     public var analysisPlatform: String = "jvm",
     public var perPackageOptions: List<PackageOptionsImpl> = emptyList(),
     public var externalDocumentationLinks: List<ExternalDocumentationLinkImpl> = emptyList(),
-    public var sourceLinks: List<SourceLinkDefinitionImpl> = emptyList()
+    public var sourceLinks: List<SourceLinkDefinitionImpl> = emptyList(),
+    public var suppressedAnnotations: Set<String> = DokkaDefaults.suppressedAnnotations
 ) {
     @Suppress("DEPRECATION")
     public fun build(): DokkaSourceSetImpl {
@@ -137,6 +138,7 @@ public class DokkaSourceSetBuilder(
             noStdlibLink = noStdlibLink,
             noJdkLink = noJdkLink,
             suppressedFiles = suppressedFiles.map(::File).toSet(),
+            suppressedAnnotations = suppressedAnnotations,
             analysisPlatform = Platform.fromString(analysisPlatform)
         )
     }