feat: implement autodoc plugin

plugins/autodoc/autodoc-extension-test/build.gradle.kts

@@ -17,14 +17,14 @@ plugins {
 
 dependencies {
     implementation(project(":runtime-metamodel"))
-    annotationProcessor(project(":plugins:autodoc:autodoc-core"))
+    annotationProcessor(project(":plugins:autodoc:autodoc-processor"))
 
 }
 
 tasks.withType<JavaCompile> {
     val compilerArgs = options.compilerArgs
     compilerArgs.add("-Aedc.version=${project.version}")
     compilerArgs.add("-Aedc.id=${project.group}:${project.name}")
-    compilerArgs.add("-Aedc.location=${project.projectDir.absolutePath}/build")
+    compilerArgs.add("-Aedc.outputdir=${project.projectDir.absolutePath}/build")
     outputs.upToDateWhen { false }
 }

plugins/autodoc/autodoc-plugin/README.md

@@ -1,3 +1,3 @@
 This module contains a gradle plugin the uses
-the [autodoc annotation processor](../autodoc-core/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/core/processor/EdcModuleProcessor.java)
+the [autodoc annotation processor](../autodoc-processor/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/core/processor/EdcModuleProcessor.java)
 to generate documentation and generate the manifest JSON file. 

plugins/autodoc/autodoc-plugin/build.gradle.kts

@@ -14,7 +14,7 @@ gradlePlugin {
     plugins {
         create("autodoc") {
             id = "autodoc"
-            implementationClass = "org.eclipse.dataspaceconnector.plugins.AutodocPlugin"
+            implementationClass = "org.eclipse.dataspaceconnector.plugins.autodoc.AutodocPlugin"
         }
     }
 }
@@ -43,6 +43,6 @@ pluginBundle {
     website = "https://projects.eclipse.org/proposals/eclipse-dataspace-connector"
     vcsUrl = "http://github.com/eclipse-dataspaceconnector/"
     group = groupId
-    version = version
+    version = version.toString().replace("-SNAPSHOT", "") // plugins cannot have SNAPSHOT version, strip off
     tags = listOf("build", "documentation", "generated", "autodoc")
 }

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/AutodocDependencyInjector.java

@@ -0,0 +1,81 @@
+/*
+ *  Copyright (c) 2022 Microsoft Corporation
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Microsoft Corporation - initial API and implementation
+ *
+ */
+
+package org.eclipse.dataspaceconnector.plugins.autodoc;
+
+import org.gradle.api.Project;
+import org.gradle.api.artifacts.DependencyResolutionListener;
+import org.gradle.api.artifacts.ResolvableDependencies;
+import org.gradle.api.tasks.compile.JavaCompile;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.List;
+import java.util.function.Supplier;
+
+import static java.lang.String.format;
+
+/**
+ * Adds an {@code annotationProcessor("...")} dependency to the project
+ */
+class AutodocDependencyInjector implements DependencyResolutionListener {
+    private static final String ANNOTATION_PROCESSOR = "annotationProcessor";
+    private static final String VERSION = "edc.version"; // must be identical to EdcModuleProcessor.VERSION
+    private static final String ID = "edc.id"; // must be identical to EdcModuleProcessor.ID
+    private final Project project;
+    private final String dependencyName;
+    private final Supplier<String> versionSupplier;
+
+    AutodocDependencyInjector(Project project, String dependencyName, Supplier<String> versionProvider) {
+        this.project = project;
+        this.dependencyName = dependencyName;
+        versionSupplier = versionProvider;
+    }
+
+    @Override
+    public void beforeResolve(@NotNull ResolvableDependencies dependencies) {
+        var artifact = dependencyName + versionSupplier.get();
+        if (addDependency(project, artifact)) {
+            var task = project.getTasks().findByName("compileJava");
+            if ((task instanceof JavaCompile)) {
+                var compileJava = (JavaCompile) task;
+                var versionArg = format("-A%s=%s", VERSION, project.getVersion());
+                var idArg = format("-A%s=%s:%s", ID, project.getGroup(), project.getName());
+
+                compileJava.getOptions().getCompilerArgs().addAll(List.of(idArg, versionArg));
+            }
+        }
+        project.getGradle().removeListener(this);
+    }
+
+    @Override
+    public void afterResolve(@NotNull ResolvableDependencies dependencies) {
+
+    }
+
+    /**
+     * Adds an {@code annotationProcessor} dependency to the given project.
+     *
+     * @param project        The Gradle project, to which the annotationProcessor dep is to be added
+     * @param dependencyName The fully qualified maven coordinates (GROUPID:ARTIFACT:VERSION) of te dependency
+     * @return true if the dependency was added successfully, false if the project does not have an {@code annotationProcessor} configuration, or the dep could not be added.
+     */
+    private boolean addDependency(Project project, String dependencyName) {
+        var apConfig = project.getConfigurations().findByName(ANNOTATION_PROCESSOR);
+        if (apConfig != null) {
+            project.getLogger().debug("autodoc: Add dependency annotationProcessor(\"{}\") to project {}", dependencyName, project.getName());
+            return apConfig.getDependencies().add(project.getDependencies().create(dependencyName));
+        }
+        return false;
+    }
+}

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/GenerateDocumentationTask.java → plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/AutodocExtension.java

@@ -14,20 +14,13 @@
 
 package org.eclipse.dataspaceconnector.plugins.autodoc;
 
-import org.gradle.api.DefaultTask;
-import org.gradle.api.tasks.TaskAction;
-
-/**
- * Enhanced task to download an artifact from a remote repository
- */
-public abstract class GenerateDocumentationTask extends DefaultTask {
+import org.gradle.api.provider.Property;
 
+public abstract class AutodocExtension {
     /**
-     * Generates documentation
+     * Override the version of the annotation processor module to use. The default is to take the same version as the plugin.
      */
-    @TaskAction
-    public void generateDocumentation() {
-        System.out.println("Generating documentation...");
-    }
+    public abstract Property<String> getProcessorVersion();
+
 
-}
+}

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/AutodocPlugin.java

@@ -16,13 +16,62 @@
 
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
+import org.gradle.api.artifacts.Configuration;
+import org.gradle.api.artifacts.ModuleVersionIdentifier;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.function.Supplier;
+
+import static java.lang.String.format;
 
 /**
- * Gradle plugin to download an arbitrary artifact from a remote repository
+ * Gradle plugin that injects an {@code annotationProcessor} dependency to any Gradle project so that the autodoc processor can run during compile.
  */
 public class AutodocPlugin implements Plugin<Project> {
+
+    private static final String PROCESSOR_ARTIFACT_NAME = "autodoc-processor";
+    private static final String PLUGIN_ARTIFACT_NAME = "autodoc-plugin";
+    private static final String GROUP_NAME = "org.eclipse.dataspaceconnector";
+
+
     @Override
-    public void apply(Project project) {
-        project.getTasks().register("autodoc", GenerateDocumentationTask.class);
+    public void apply(@NotNull Project project) {
+
+        project.getExtensions().create("audodocextension", AutodocExtension.class);
+
+
+        // adds the annotation processor dependency
+        project.getGradle().addListener(new AutodocDependencyInjector(project, format("%s:%s:", GROUP_NAME, PROCESSOR_ARTIFACT_NAME),
+                createVersionProvider(project)));
+
+        // registers a "named" task, that does nothing, except depend on the compileTask, which then runs the annotation processor
+        project.getTasks().register("autodoc", t -> t.dependsOn("compileJava"));
+
+    }
+
+    private Supplier<String> createVersionProvider(Project project) {
+        return () -> {
+            // runtime version of the actual annotation processor, or override in config
+            var versionToUse = getProcessorModuleVersion(project);
+
+            var extension = project.getExtensions().findByType(AutodocExtension.class);
+            if (extension != null && extension.getProcessorVersion().isPresent()) {
+                versionToUse = extension.getProcessorVersion().get();
+                project.getLogger().debug("{}: use configured version from AutodocExtension (override) [{}]", project.getName(), versionToUse);
+            } else {
+                project.getLogger().debug("{}: use default version [{}]", project.getName(), versionToUse);
+            }
+            return versionToUse;
+        };
+    }
+
+    private String getProcessorModuleVersion(Project project) {
+        Configuration classpath = project.getRootProject().getBuildscript().getConfigurations().getByName("classpath");
+        return classpath.getResolvedConfiguration().getResolvedArtifacts().stream()
+                .map(artifact -> artifact.getModuleVersion().getId())
+                .filter(id -> GROUP_NAME.equals(id.getGroup()) && PLUGIN_ARTIFACT_NAME.equals(id.getName()))
+                .findAny()
+                .map(ModuleVersionIdentifier::getVersion)
+                .orElse(null);
     }
 }

plugins/autodoc/autodoc-core/build.gradle.kts → plugins/autodoc/autodoc-processor/build.gradle.kts

@@ -21,8 +21,8 @@ dependencies {
 
 publishing {
     publications {
-        create<MavenPublication>("autodoc-core") {
-            artifactId = "autodoc-core"
+        create<MavenPublication>("autodoc-processor") {
+            artifactId = "autodoc-processor"
             from(components["java"])
         }
     }

plugins/autodoc/autodoc-core/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/core/processor/EdcModuleProcessor.java → plugins/autodoc/autodoc-processor/src/main/java/org/eclipse/dataspaceconnector/plugins/autodoc/core/processor/EdcModuleProcessor.java

@@ -48,11 +48,11 @@
  * <p>
  * Two processor parameters must be set: {@link #ID} which by convention uses Maven group id an artifact id coordinates;
  * and {@link #VERSION}. To Override the location where the manifest is generated, specify
- * {@link #EDC_LOCATION_OVERRIDE} as a processor parameter.
+ * {@link #EDC_OUTPUTDIR_OVERRIDE} as a processor parameter.
  */
 @SupportedAnnotationTypes({
-        "org.eclipse.dataspaceconnector.runtime.metamodel.annotationEdcSetting",
-        "org.eclipse.dataspaceconnector.runtime.metamodel.annotationEdcSettingContext",
+        "org.eclipse.dataspaceconnector.runtime.metamodel.annotation.EdcSetting",
+        "org.eclipse.dataspaceconnector.runtime.metamodel.annotation.EdcSettingContext",
         "org.eclipse.dataspaceconnector.runtime.metamodel.annotation.Extension",
         "org.eclipse.dataspaceconnector.runtime.metamodel.annotation.Spi",
         "org.eclipse.dataspaceconnector.runtime.metamodel.annotation.ExtensionPoint",
@@ -64,12 +64,10 @@
 @SupportedSourceVersion(SourceVersion.RELEASE_11)
 @SupportedOptions({ EdcModuleProcessor.ID, EdcModuleProcessor.VERSION })
 public class EdcModuleProcessor extends AbstractProcessor {
-    static final String VERSION = "edc.version";
-    static final String ID = "edc.id";
-
+    public static final String VERSION = "edc.version";
+    public static final String ID = "edc.id";
+    public static final String EDC_OUTPUTDIR_OVERRIDE = "edc.outputdir";
     private static final String MANIFEST_NAME = "edc.json";
-    private static final String EDC_LOCATION_OVERRIDE = "edc.location";
-
     private final ObjectMapper mapper = new ObjectMapper();
 
     private ModuleIntrospector moduleIntrospector;
@@ -158,7 +156,7 @@ private ModuleType determineAndValidateModuleType(RoundEnvironment environment)
                 processingEnv.getMessager().printMessage(ERROR, "Multiple SPI definitions found in module: " + types);
                 return null;
             } else if (spiElements.isEmpty()) {
-                processingEnv.getMessager().printMessage(NOTE, "Note an EDC module. Skipping module processing.");
+                processingEnv.getMessager().printMessage(NOTE, "Not an EDC module. Skipping module processing.");
                 return null;
             }
             return ModuleType.SPI;
@@ -177,7 +175,7 @@ private ModuleType determineAndValidateModuleType(RoundEnvironment environment)
     private void writeManifest() {
         try {
             var filer = processingEnv.getFiler();
-            var location = processingEnv.getOptions().get(EDC_LOCATION_OVERRIDE);
+            var location = processingEnv.getOptions().get(EDC_OUTPUTDIR_OVERRIDE);
             if (location != null) {
                 new File(location).mkdirs();
                 try (var writer = new BufferedWriter(new FileWriter(location + File.separator + MANIFEST_NAME))) {

plugins/autodoc/autodoc-spi-test/build.gradle.kts

@@ -17,12 +17,12 @@ plugins {
 
 dependencies {
     implementation(project(":runtime-metamodel"))
-    annotationProcessor(project(":plugins:autodoc:autodoc-core"))
+    annotationProcessor(project(":plugins:autodoc:autodoc-processor"))
 }
 
 tasks.withType<JavaCompile> {
     val compilerArgs = options.compilerArgs
     compilerArgs.add("-Aedc.version=${project.version}")
     compilerArgs.add("-Aedc.id=${project.group}:${project.name}")
-    compilerArgs.add("-Aedc.location=${project.projectDir.absolutePath}/build")
+    compilerArgs.add("-Aedc.outputdir=${project.projectDir.absolutePath}/build")
 }

settings.gradle.kts

@@ -1,7 +1,7 @@
 rootProject.name = "edcPlugins"
 
 include("plugins:autodoc:autodoc-plugin")
-include("plugins:autodoc:autodoc-core")
+include("plugins:autodoc:autodoc-processor")
 include("plugins:autodoc:autodoc-extension-test")
 include("plugins:autodoc:autodoc-spi-test")
 include("runtime-metamodel")