From 937b5ac16d94c95715fc61e4167772430de56d2a Mon Sep 17 00:00:00 2001 From: James Strachan Date: Thu, 5 Apr 2012 15:45:46 +0100 Subject: [PATCH] added first spike of a kdoc maven plugin for generating API docs for kotlin projects --- libraries/apidoc/pom.xml | 66 +++++++ libraries/kdoc-maven-plugin/ReadMe.md | 8 + libraries/kdoc-maven-plugin/pom.xml | 56 ++++++ .../jetbrains/kotlin/maven/doc/KDocMojo.java | 164 ++++++++++++++++++ .../org/jetbrains/kotlin/maven/MojoTest.java | 26 +++ libraries/kdoc/pom.xml | 1 - libraries/pom.xml | 2 + 7 files changed, 322 insertions(+), 1 deletion(-) create mode 100644 libraries/apidoc/pom.xml create mode 100644 libraries/kdoc-maven-plugin/ReadMe.md create mode 100644 libraries/kdoc-maven-plugin/pom.xml create mode 100644 libraries/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java create mode 100644 libraries/kdoc-maven-plugin/src/test/java/org/jetbrains/kotlin/maven/MojoTest.java diff --git a/libraries/apidoc/pom.xml b/libraries/apidoc/pom.xml new file mode 100644 index 00000000000..37de80df542 --- /dev/null +++ b/libraries/apidoc/pom.xml @@ -0,0 +1,66 @@ + + + + 4.0.0 + + + org.jetbrains.kotlin + kotlin-project + 1.0-SNAPSHOT + + + apidoc + + + + org.jetbrains.kotlin + stdlib + ${project.version} + + + junit + junit + ${junit-version} + + + + + + + org.jetbrains.kotlin + kdoc-maven-plugin + ${project.version} + + + ${basedir}/../stdlib/src + ${basedir}/../kunit/src/main/kotlin + ${basedir}/../kotlin-jdbc/src/main/kotlin + ${basedir}/../kotlin-swing/src/main/kotlin + + Kotlin API (${project.version}) + + com + sun + java + jet + junit + org + + + + + + + apidoc + install + + apidoc + + + + + + + diff --git a/libraries/kdoc-maven-plugin/ReadMe.md b/libraries/kdoc-maven-plugin/ReadMe.md new file mode 100644 index 00000000000..12d243d5035 --- /dev/null +++ b/libraries/kdoc-maven-plugin/ReadMe.md @@ -0,0 +1,8 @@ +## KDoc Maven Plugin + +This Maven plugin allows you to create API Documentation for your Kotlin code (rather like javadoc but more kool :) +as it allows embedded [markdown](http://daringfireball.net/projects/markdown/syntax#block) wiki markup. + +For examples check out the [Kotlin API docs](http://jetbrains.github.com/kotlin/versions/snapshot/apidocs/index.html). + +For more details see [how to write code with comments](http://confluence.jetbrains.net/display/Kotlin/Coding+Conventions) \ No newline at end of file diff --git a/libraries/kdoc-maven-plugin/pom.xml b/libraries/kdoc-maven-plugin/pom.xml new file mode 100644 index 00000000000..7f38078528e --- /dev/null +++ b/libraries/kdoc-maven-plugin/pom.xml @@ -0,0 +1,56 @@ + + + + 4.0.0 + + 1.4.1 + 3.0.4 + + + + org.jetbrains.kotlin + kotlin-project + 1.0-SNAPSHOT + + + kdoc-maven-plugin + maven-plugin + + + + org.jetbrains.kotlin + kotlin-maven-plugin + ${project.version} + + + org.jetbrains.kotlin + kdoc + ${project.version} + + + org.pegdown + pegdown + ${pegdown.version} + + + + + src/main/java + src/test/java + + + + org.apache.maven.plugins + maven-compiler-plugin + + + + org.apache.maven.plugins + maven-plugin-plugin + 2.9 + + + + diff --git a/libraries/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java b/libraries/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java new file mode 100644 index 00000000000..9c4e1c70aff --- /dev/null +++ b/libraries/kdoc-maven-plugin/src/main/java/org/jetbrains/kotlin/maven/doc/KDocMojo.java @@ -0,0 +1,164 @@ +/* + * Copyright 2010-2012 JetBrains s.r.o. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.jetbrains.kotlin.maven.doc; + +import org.apache.maven.plugin.MojoExecutionException; +import org.jetbrains.jet.cli.CompilerArguments; +import org.jetbrains.jet.cli.KotlinCompiler; +import org.jetbrains.kotlin.doc.KDocArguments; +import org.jetbrains.kotlin.doc.KDocCompiler; +import org.jetbrains.kotlin.doc.KDocConfig; +import org.jetbrains.kotlin.maven.KotlinCompileMojoBase; + +import java.util.List; + +/** + * Generates API docs documentation for kotlin sources + * + * @goal apidoc + * @phase site + * @requiresDependencyResolution test + * @noinspection UnusedDeclaration + */ +public class KDocMojo extends KotlinCompileMojoBase { + + /** + * Project classpath. + * + * @parameter default-value="${project.compileClasspathElements}" + * @required + * @readonly + */ + public List classpath; + + /** + * Project test classpath. + * + * @parameter default-value="${project.testClasspathElements}" + * @required + * @readonly + */ + protected List testClasspath; + + /** + * The directory for compiled apidoc classes. + * + * @parameter default-value="${project.build.outputDirectory}" + * @required + * @readonly + */ + public String output; + + + // TODO not sure why default is stopping us passing this value in via a config + // default-value="${project.compileSourceRoots}" + + /** + * The sources used to compile + * + * @parameter expression="${sources}" + * @required + */ + private List sources; + + /** + * The directory for the generated KDocs + * + * @parameter expression="${docOutputDir}" default-value="${basedir}/target/site/apidocs" + * @required + */ + private String docOutputDir; + + /** + * The module to use for documentation + * + * @parameter expression="${docModule}" + */ + private String docModule; + + /** + * Package prefixes which are excluded from the kdoc + * + * @parameter expression="${ignorePackages}" + */ + protected List ignorePackages; + + /** + * Whether protected classes, functions and properties should be included + * + * @parameter expression="${includeProtected}" default-value="true" + */ + private boolean includeProtected; + + /** + * The title of the documentation + * + * @parameter expression="${title}" default-value="KDoc for ${project.artifactId}" + */ + private String title; + + /** + * The version of the documentation + * + * @parameter expression="${version}" default-value="KDoc for ${project.version" + */ + private String version; + + /** + * Whether warnings should be generated if no comments could be found for classes, functions and properties being documented + * + * @parameter expression="${warnNoComments}" default-value="true" + */ + private boolean warnNoComments; + + @Override + protected KotlinCompiler createCompiler() { + return new KDocCompiler(); + } + + @Override + protected CompilerArguments createCompilerArguments() { + return new KDocArguments(); + } + + @Override + protected void configureCompilerArguments(CompilerArguments arguments) throws MojoExecutionException { + configureBaseCompilerArguments(getLog(), arguments, docModule, sources, classpath, output); + + if (arguments instanceof KDocArguments) { + KDocArguments kdoc = (KDocArguments) arguments; + KDocConfig docConfig = kdoc.getDocConfig(); + docConfig.setDocOutputDir(docOutputDir); + if (ignorePackages != null) { + docConfig.getIgnorePackages().addAll(ignorePackages); + } + docConfig.setIncludeProtected(includeProtected); + docConfig.setTitle(title); + docConfig.setVersion(version); + docConfig.setWarnNoComments(warnNoComments); + getLog().info("API docs output to: " + docConfig.getDocOutputDir()); + getLog().info("classpath: " + classpath); + getLog().info("title: " + title); + getLog().info("sources: " + sources); + getLog().info("API docs ignore packages: " + ignorePackages); + } else { + getLog().warn("No KDocArguments available!"); + } + + } +} + diff --git a/libraries/kdoc-maven-plugin/src/test/java/org/jetbrains/kotlin/maven/MojoTest.java b/libraries/kdoc-maven-plugin/src/test/java/org/jetbrains/kotlin/maven/MojoTest.java new file mode 100644 index 00000000000..a3b38e59d90 --- /dev/null +++ b/libraries/kdoc-maven-plugin/src/test/java/org/jetbrains/kotlin/maven/MojoTest.java @@ -0,0 +1,26 @@ +/* + * Copyright 2010-2012 JetBrains s.r.o. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.jetbrains.kotlin.maven; + +import org.junit.Test; + +public class MojoTest { + @Test + public void dummy() { + + } +} diff --git a/libraries/kdoc/pom.xml b/libraries/kdoc/pom.xml index 32513db3b75..db9a493deec 100644 --- a/libraries/kdoc/pom.xml +++ b/libraries/kdoc/pom.xml @@ -20,7 +20,6 @@ ${pegdown.version} - org.jetbrains.kotlin kotlin-maven-plugin diff --git a/libraries/pom.xml b/libraries/pom.xml index 93bffa9dd6e..f8c358cfa4a 100644 --- a/libraries/pom.xml +++ b/libraries/pom.xml @@ -32,6 +32,7 @@ kotlin-install runtime kotlin-maven-plugin + kdoc-maven-plugin kunit stdlib kdoc @@ -39,6 +40,7 @@ kotlin-java kotlin-swing website + apidoc examples