Therapi-based Discovery

pom.xml

@@ -48,11 +48,13 @@
 		<module>imagej/imagej-ops2</module>
 		<module>imagej/imagej-testutil</module>
 		<module>scijava/scijava-discovery</module>
+		<module>scijava/scijava-discovery-therapi</module>
 		<module>scijava/scijava-function</module>
 		<module>scijava/scijava-ops-api</module>
 		<module>scijava/scijava-ops-engine</module>
 		<module>scijava/scijava-ops-serviceloader</module>
 		<module>scijava/scijava-ops-spi</module>
+		<module>scijava/scijava-parse2</module>
 		<module>scijava/scijava-persist</module>
 		<module>scijava/scijava-progress</module>
 		<module>scijava/scijava-struct</module>
@@ -98,6 +100,7 @@
 		<therapi.version>0.12.0</therapi.version>
 		<therapi-runtime-javadoc.version>${therapi.version}</therapi-runtime-javadoc.version>
 		<therapi-runtime-javadoc-scribe.version>${therapi.version}</therapi-runtime-javadoc-scribe.version>
+		<therapi.packages>-</therapi.packages>
 	</properties>
 
 	<build>
@@ -117,6 +120,10 @@
 							<version>${scijava-common.version}</version>
 						</path>
 					</annotationProcessorPaths>
+					<fork>true</fork>
+					<compilerArgs>
+						<arg>-Ajavadoc.packages="${therapi.packages}"</arg>
+					</compilerArgs>
 				</configuration>
 			</plugin>
 			<plugin>

scijava/scijava-discovery-therapi/.gitignore

@@ -0,0 +1,2 @@
+/.apt_generated/
+/.apt_generated_tests/

scijava/scijava-discovery-therapi/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2016 - 2019, SciJava Ops developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

scijava/scijava-discovery-therapi/README.md

@@ -0,0 +1,67 @@
+# SciJava Discovery Therapi: A Discoverer implementation backed by Therapi
+
+This module provides the `TherapiDiscover`, a `Discoverer` implementation that uses [`therapi-runtime-javadoc`](https://github.com/dnault/therapi-runtime-javadoc) to discover tagged elements through javadoc tags.
+
+`TherapiDiscoverer` **only** implements `Discoverer.elementsTaggedWith(String tag)`.
+
+To make tags discoverable via `TherapiDiscoverer`, one must first enable therapi's annotation processor.
+
+```java
+<properties>
+	<therapi.version>0.12.0</therapi.version>
+	<therapi-runtime-javadoc-scribe.version>${therapi.version}</therapi-runtime-javadoc-scribe.version>
+	<therapi.packages></therapi.packages>
+</properties>
+```
+
+This sets the therapi version, and denotes the packages (using the `<therapi.packages>` tag) that should be processed. This can be left blank to indicate all packages, or can be a comma-delimited list to process **only** those packages.
+
+```java
+<build>
+	<plugins>
+		<plugin>
+			<artifactId>maven-compiler-plugin</artifactId>
+			<configuration>
+				<annotationProcessorPaths>
+					<path>
+						<groupId>com.github.therapi</groupId>
+						<artifactId>therapi-runtime-javadoc-scribe</artifactId>
+						<version>${therapi-runtime-javadoc-scribe.version}</version>
+					</path>
+				</annotationProcessorPaths>
+				<fork>true</fork>
+				<compilerArgs>
+					<arg>-Ajavadoc.packages="${therapi.packages}"</arg>
+				</compilerArgs>
+			</configuration>
+		</plugin>
+	</plugins>
+</build>
+```
+
+These elements already live in `scijava-incubator`, and will be moved upstream to `pom-scijava` at a later date. This means that all incubator projects (and later all SciJava projects) will have therapi capabilities for free. This behavior is **opt-in**; to enable therapi's annotation processor (and thus any functionality from `TherapiDiscoverer`) one must add `<therapi.packages></therapi.packages>` to the `properties` section of their POM.
+
+## Tag Structure
+
+To add a tag to any [`AnnotatedElement`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/reflect/AnnotatedElement.html), one can simply insert the [`@implNote`](https://nipafx.dev/javadoc-tags-apiNote-implSpec-implNote/) tag into the javadoc of that `AnnotatedElement`. Tags should be structured as
+
+```java
+@implNote <tagType> <tagBody>
+```
+
+Where `tagType` is the `String` under which this `AnnotatedElement` should be discovered, and `tagBody` is any set of options relevant for the `tagType`. **TODO: `tagBody` structure**
+
+An example might look like
+
+```java
+
+/**
+ * @implNote foo 
+ */
+public void taggedMethod(...) {
+  ...
+}
+```
+
+Assuming therapi processes the package containing `taggedMethod`, `taggedMethod` can then be retrieved using `TherapiDiscoverer.elementsTaggedWith("foo")`.
+

scijava/scijava-discovery-therapi/pom.xml

@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>org.scijava</groupId>
+		<artifactId>scijava-incubator</artifactId>
+		<version>0-SNAPSHOT</version>
+		<relativePath>../..</relativePath>
+	</parent>
+
+	<artifactId>scijava-discovery-therapi</artifactId>
+
+	<name>SciJava Discovery Therapi</name>
+	<description>SciJava Discovery Therapi: A therapi-aided Discovery implementation</description>
+	<url>https://github.com/scijava/scijava</url>
+	<inceptionYear>2021</inceptionYear>
+	<organization>
+		<name>SciJava</name>
+		<url>https://scijava.org/</url>
+	</organization>
+	<licenses>
+		<license>
+			<name>Simplified BSD License</name>
+			<distribution>repo</distribution>
+		</license>
+	</licenses>
+
+	<developers>
+		<developer>
+			<id>ctrueden</id>
+			<name>Curtis Rueden</name>
+			<url>https://imagej.net/User:Rueden</url>
+			<roles>
+				<role>founder</role>
+				<role>reviewer</role>
+				<role>support</role>
+				<role>maintainer</role>
+			</roles>
+		</developer>
+		<developer>
+			<id>gselzer</id>
+			<name>Gabriel Selzer</name>
+			<roles>
+				<role>founder</role>
+				<role>lead</role>
+				<role>developer</role>
+				<role>debugger</role>
+				<role>reviewer</role>
+				<role>support</role>
+			</roles>
+		</developer>
+	</developers>
+	<contributors>
+		<contributor>
+			<name>None</name>
+		</contributor>
+	</contributors>
+
+	<mailingLists>
+		<mailingList>
+			<name>Image.sc Forum</name>
+			<archive>https://forum.image.sc/tags/scijava-discovery-therapi</archive>
+		</mailingList>
+	</mailingLists>
+
+	<scm>
+		<connection>scm:git:git://github.com/scijava/incubator</connection>
+		<developerConnection>scm:git:[email protected]:scijava/incubator</developerConnection>
+		<tag>HEAD</tag>
+		<url>https://github.com/scijava/incubator</url>
+	</scm>
+	<issueManagement>
+		<system>GitHub Issues</system>
+		<url>https://github.com/scijava/scijava/issues</url>
+	</issueManagement>
+	<ciManagement>
+		<system>Travis CI</system>
+		<url>https://travis-ci.com/scijava/incubator</url>
+	</ciManagement>
+
+	<properties>
+		<package-name>org.scijava.discovery.therapi</package-name>
+
+		<license.licenseName>bsd_2</license.licenseName>
+		<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
+		<scijava-discovery-therapi.allowedDuplicateClasses>
+			${scijava.allowedDuplicateClasses}
+		</scijava-discovery-therapi.allowedDuplicateClasses>
+		<allowedDuplicateClasses>${scijava-discovery-therapi.allowedDuplicateClasses}</allowedDuplicateClasses>
+		<therapi.packages></therapi.packages>
+	</properties>
+	<dependencies>
+		<dependency>
+			<groupId>com.github.therapi</groupId>
+			<artifactId>therapi-runtime-javadoc</artifactId>
+			<version>${therapi-runtime-javadoc.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>org.scijava</groupId>
+			<artifactId>scijava-discovery</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>org.scijava</groupId>
+			<artifactId>scijava-parse2</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>org.scijava</groupId>
+			<artifactId>scijava-common</artifactId>
+		</dependency>
+		<!-- Test scope dependencies -->
+		<dependency>
+			<groupId>junit</groupId>
+			<artifactId>junit</artifactId>
+			<scope>test</scope>
+		</dependency>
+	</dependencies>
+</project>

scijava/scijava-discovery-therapi/src/main/java/module-info.java

@@ -0,0 +1,9 @@
+module org.scijava.discovery.therapi {
+
+	exports org.scijava.discovery.therapi;
+	opens org.scijava.discovery.therapi to therapi.runtime.javadoc;
+
+	requires org.scijava.discovery;
+	requires transitive org.scijava.parse2;
+	requires therapi.runtime.javadoc;
+}