JavadocPlugin.groovy
001 /*
002  * SPDX-License-Identifier: Apache-2.0
003  *
004  * Copyright 2018-2019 Andres Almiray.
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 package org.kordamp.gradle.plugin.javadoc
019 
020 import groovy.transform.CompileDynamic
021 import groovy.transform.CompileStatic
022 import org.gradle.api.Action
023 import org.gradle.api.JavaVersion
024 import org.gradle.api.Project
025 import org.gradle.api.Task
026 import org.gradle.api.plugins.JavaBasePlugin
027 import org.gradle.api.tasks.bundling.Jar
028 import org.gradle.api.tasks.javadoc.Javadoc
029 import org.kordamp.gradle.plugin.AbstractKordampPlugin
030 import org.kordamp.gradle.plugin.base.BasePlugin
031 import org.kordamp.gradle.plugin.base.ProjectConfigurationExtension
032 
033 import static org.kordamp.gradle.PluginUtils.resolveEffectiveConfig
034 import static org.kordamp.gradle.plugin.base.BasePlugin.isRootProject
035 
036 /**
037  * Configures {@code javadoc} and {@code javadocJar} tasks.
038  *
039  @author Andres Almiray
040  @since 0.1.0
041  */
042 @CompileStatic
043 class JavadocPlugin extends AbstractKordampPlugin {
044     static final String JAVADOC_TASK_NAME = 'javadoc'
045     static final String JAVADOC_JAR_TASK_NAME = 'javadocJar'
046 
047     Project project
048 
049     void apply(Project project) {
050         this.project = project
051 
052         if (isRootProject(project)) {
053             if (project.childProjects.size()) {
054                 project.childProjects.values().each {
055                     configureProject(it)
056                 }
057             else {
058                 configureProject(project)
059             }
060         else {
061             configureProject(project)
062         }
063     }
064 
065     static void applyIfMissing(Project project) {
066         if (!project.plugins.findPlugin(JavadocPlugin)) {
067             project.plugins.apply(JavadocPlugin)
068         }
069     }
070 
071     @CompileDynamic
072     private void configureProject(Project project) {
073         if (hasBeenVisited(project)) {
074             return
075         }
076         setVisited(project, true)
077 
078         BasePlugin.applyIfMissing(project)
079 
080         project.tasks.register('checkAutoLinks', CheckAutoLinksTask.class,
081             new Action<CheckAutoLinksTask>() {
082                 void execute(CheckAutoLinksTask t) {
083                     t.group = 'Documentation'
084                     t.description = 'Checks if generated Javadoc auto links are reachable.'
085                 }
086             })
087 
088         project.afterEvaluate {
089             ProjectConfigurationExtension effectiveConfig = resolveEffectiveConfig(project)
090             setEnabled(effectiveConfig.javadoc.enabled)
091 
092             if (!enabled) {
093                 return
094             }
095 
096             project.plugins.withType(JavaBasePlugin) {
097                 Task javadoc = createJavadocTaskIfNeeded(project)
098                 if (!javadocreturn
099                 effectiveConfig.javadoc.javadocTasks() << javadoc
100 
101                 Task javadocJar = createJavadocJarTask(project, javadoc)
102                 project.tasks.findByName(org.gradle.api.plugins.BasePlugin.ASSEMBLE_TASK_NAME).dependsOn(javadocJar)
103                 effectiveConfig.javadoc.javadocJarTasks() << javadocJar
104 
105                 effectiveConfig.javadoc.projects() << project
106             }
107 
108             project.tasks.withType(Javadoc) { Javadoc task ->
109                 effectiveConfig.javadoc.applyTo(task)
110                 task.options.footer = "Copyright &copy; ${effectiveConfig.info.copyrightYear} ${effectiveConfig.info.getAuthors().join(', ')}. All rights reserved."
111 
112                 if (JavaVersion.current().isJava8Compatible()) {
113                     task.options.addStringOption('Xdoclint:none', '-quiet')
114                 }
115             }
116         }
117     }
118 
119     @CompileDynamic
120     private Task createJavadocTaskIfNeeded(Project project) {
121         String taskName = JAVADOC_TASK_NAME
122 
123         Javadoc javadocTask = project.tasks.findByName(taskName)
124         Task classesTask = project.tasks.findByName('classes')
125 
126         if (classesTask && !javadocTask) {
127             javadocTask = project.tasks.create(taskName, Javadoc) {
128                 dependsOn classesTask
129                 group JavaBasePlugin.DOCUMENTATION_GROUP
130                 description 'Generates Javadoc API documentation'
131                 source project.sourceSets.main.allSource
132                 destinationDir project.file("${project.buildDir}/docs/javadoc")
133             }
134         }
135 
136         ProjectConfigurationExtension effectiveConfig = resolveEffectiveConfig(project)
137         javadocTask.configure {
138             include(effectiveConfig.javadoc.includes)
139             exclude(effectiveConfig.javadoc.excludes)
140         }
141 
142         javadocTask
143     }
144 
145     @CompileDynamic
146     private Task createJavadocJarTask(Project project, Task javadoc) {
147         String taskName = JAVADOC_JAR_TASK_NAME
148 
149         Task javadocJarTask = project.tasks.findByName(taskName)
150 
151         if (!javadocJarTask) {
152             javadocJarTask = project.tasks.create(taskName, Jar) {
153                 dependsOn javadoc
154                 group JavaBasePlugin.DOCUMENTATION_GROUP
155                 description 'An archive of the Javadoc API docs'
156                 classifier 'javadoc'
157                 from javadoc.destinationDir
158             }
159         }
160 
161         javadocJarTask
162     }
163 }