Disable custom javadoc taglets for methods/classes

gselzer · ctrueden · commit a8d6335635ea · 2021-11-15T17:25:20.000-06:00
This ensures that everyone will be writing proper javadoc whenever
proper javadoc will be sufficient for our purposes
diff --git a/scijava/scijava-ops/src/main/java/org/scijava/param/JavadocParameterData.java b/scijava/scijava-ops/src/main/java/org/scijava/param/JavadocParameterData.java
@@ -148,15 +148,12 @@ private void parseMethod(Method m) {
 		MethodJavadoc doc = RuntimeJavadoc.getJavadoc(m);
 		long numOpParams = getOpParams(m);
 		long numReturns = m.getReturnType() == void.class ? 0 : 1;
-		// scrape the conventional javadoc tags iff present
-		if (hasVanillaJavadoc(doc, numOpParams, numReturns))
-			populateViaParamAndReturn(doc.getParams(), doc.getReturns());
-		// scrape our custom javadoc taglets iff present
-		else if (hasCustomJavadoc(doc.getOther(), numOpParams, 1))
-			populateViaCustomTaglets(doc.getOther());
-		// give up if neither is fully present
-		else throw new IllegalArgumentException("Method " + m +
-			" has no suitable tag(lets) to scrape documentation from");
+		// ensure the method declares a complete set of tags
+		if (!hasVanillaJavadoc(doc, numOpParams, numReturns))
+			throw new IllegalArgumentException("Method " + m +
+				" has no suitable tag(lets) to scrape documentation from");
+		// scrape the conventional javadoc tags
+		populateViaParamAndReturn(doc.getParams(), doc.getReturns());
 	}
 
 	private long getOpParams(Method m) {
@@ -181,7 +178,7 @@ private boolean hasVanillaJavadoc(MethodJavadoc doc, long numParams, long numRet
 		// We require a @param tag for each of the method parameters
 		boolean sufficientParams = doc.getParams().size() == numParams;
 		// We require a @return tag for the method return iff not null
-		boolean javadocReturn = doc.getReturns() != null;
+		boolean javadocReturn = !doc.getReturns().toString().isEmpty();
 		boolean methodReturn = numReturns == 1;
 		boolean sufficientReturn = javadocReturn == methodReturn;
 		return sufficientParams && sufficientReturn;
diff --git a/scijava/scijava-ops/src/test/java/org/scijava/param/JavadocParameterTest.java b/scijava/scijava-ops/src/test/java/org/scijava/param/JavadocParameterTest.java
@@ -112,7 +112,7 @@ public void testJavadocMethodIO() {
 		if (infos.hasNext()) {
 			Assert.fail("Multiple OpInfos with name \"test.javadoc.method\"");
 		}
-		isSuitableScrapedOpMethodInfo(info);
+		isSuitableGenericOpMethodInfo(info);
 	}
 
 	@Test
@@ -140,7 +140,7 @@ public void testJavadocMethodI() {
 	/**
 	 * Tests javadoc scraping of mutable taglet
 	 * 
-	 * @mutable foo the i/o argument
+	 * @param foo the i/o argument
 	 */
 	@OpMethod(names = "test.javadoc.methodInplaceI", type = Inplaces.Arity1.class)
 	public static void OpMethodInplaceI(List<String> foo) {
@@ -153,7 +153,7 @@ public static void OpMethodInplaceI(List<String> foo) {
 	 * Tests javadoc scraping of mutable taglet
 	 * 
 	 * @dependency inplace the Op being wrapped
-	 * @mutable foo the i/o argument
+	 * @param foo the i/o argument
 	 */
 	@OpMethod(names = "test.javadoc.methodDependency", type = Inplaces.Arity1.class)
 	public static void OpMethodInplaceI(@OpDependency(

Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,7 @@ public void testJavadocMethodIO() {`
`112`	`112`	`if (infos.hasNext()) {`
`113`	`113`	`Assert.fail("Multiple OpInfos with name \"test.javadoc.method\"");`
`114`	`114`	`}`
`115`		`- isSuitableScrapedOpMethodInfo(info);`
	`115`	`+ isSuitableGenericOpMethodInfo(info);`
`116`	`116`	`}`
`117`	`117`
`118`	`118`	`@Test`
`@@ -140,7 +140,7 @@ public void testJavadocMethodI() {`
`140`	`140`	`/**`
`141`	`141`	`* Tests javadoc scraping of mutable taglet`
`142`	`142`	`*`
`143`		`- * @mutable foo the i/o argument`
	`143`	`+ * @param foo the i/o argument`
`144`	`144`	`*/`
`145`	`145`	`@OpMethod(names = "test.javadoc.methodInplaceI", type = Inplaces.Arity1.class)`
`146`	`146`	`public static void OpMethodInplaceI(List<String> foo) {`
`@@ -153,7 +153,7 @@ public static void OpMethodInplaceI(List<String> foo) {`
`153`	`153`	`* Tests javadoc scraping of mutable taglet`
`154`	`154`	`*`
`155`	`155`	`* @dependency inplace the Op being wrapped`
`156`		`- * @mutable foo the i/o argument`
	`156`	`+ * @param foo the i/o argument`
`157`	`157`	`*/`
`158`	`158`	`@OpMethod(names = "test.javadoc.methodDependency", type = Inplaces.Arity1.class)`
`159`	`159`	`public static void OpMethodInplaceI(@OpDependency(`