Javadoc/whitespace cleanup and slight refactoring

As dubious as combining any refactoring with a Javadoc/whitespace
cleanup may be, it was preferable to writing new Javadoc to try to
explain why it was factored as it was (with some script engine
bindings being added in PGXSUtils.getScriptEngine and others in
ScriptingMojo.execute, especially as that didn't match where the
underlying methods lived).

Adjusts javadoc options to include package-access types and members
in pljava-pgxs, as some of those are exported to the script engine
and ought to be documented.

Author: jcflack

pljava-pgxs/pom.xml

@@ -170,6 +170,8 @@ function executeReport(report, locale)
 			 */
 			"-locale",      locale.toString(),
 			"-quiet",
+			"--show-members", "package",
+			"--show-types",   "package",
 			/*
 			 * Options that are passed to the doclet.
 			 */

pljava-pgxs/src/main/java/org/postgresql/pljava/pgxs/AbstractPGXS.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2021 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2020-2024 Tada AB and other contributors, as listed below.
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the The BSD 3-Clause License
@@ -21,33 +21,59 @@
 import java.util.stream.Collectors;
 
 /**
- * Class to act as a blueprint for platform specific build configurations in
- * pljava-so/pom.xml
+ * Class to act as a blueprint for platform-specific build configurations in a
+ * {@code pom.xml}.
+ *<p>
+ * A {@code scripted-goal} configuration in the POM should contain a script
+ * that somehow selects and supplies a concrete implementation of this abstract
+ * class.
+ *<p>
+ * In {@code pljava-so/pom.xml}, a block of {@code application/javascript} is
+ * supplied that contains a {@code configuration} array of JS objects, each of
+ * which has a {@code name} entry, a {@code probe} function returning true on
+ * some supported platform, and the necessary functions to serve as an
+ * implementation of this class. The script selects one whose probe succeeds
+ * and, using JSR 223 magic, makes an instance of this class from it.
+ *<p>
+ * The script can make use of convenience methods implemented here, and also
+ * a number of items (such as a {@code runCommand} function) presupplied in the
+ * script engine's binding scope by
+ * {@link PGXSUtils#getScriptEngine PGXSUtils.getScriptEngine} and by
+ * {@link ScriptingMojo#execute ScriptingMojo.execute}).
  */
 public abstract class AbstractPGXS
 {
-
 	/**
-	 * Add instructions for compiling the pljava-so C files on your platform
-	 * by implementing this method in your configuration block.
+	 * Performs platform-specific compilation of a set of {@code .c} files with
+	 * the specified compiler, target path, includes, defines, and flags.
+	 *<p>
+	 * An implementation should make any needed adjustments to the includes,
+	 * defines, and flags, format everything appropriately for the compiler
+	 * in question, execute it, and return an exit status (zero on success).
 	 */
-	public abstract int compile(String compiler, List<String> files, Path targetPath,
-								 List<String> includes, Map<String, String> defines,
-								 List<String> flags);
+	public abstract int compile(
+		String compiler, List<String> files, Path targetPath,
+		List<String> includes, Map<String, String> defines, List<String> flags);
 
 	/**
-	 * Add instructions for linking and producing the pljava-so shared library
-	 * artifact on your platform by implementing this method in your
-	 * configuration block.
+	 * Performs platform-specific linking of a set of object files with
+	 * the specified linker and flags, to produce the shared object at the
+	 * specified target path.
+	 *<p>
+	 * An implementation should make any needed adjustments to the flags, format
+	 * everything appropriately for the linker in question, execute it, and
+	 * return an exit status (zero on success).
 	 */
-	public abstract int link(String linker, List<String> flags, List<String> files, Path targetPath);
+	public abstract int link(
+		String linker, List<String> flags, List<String> files, Path targetPath);
 
 	/**
 	 * Returns a list with all items prefixed with correct include flag symbol.
 	 *
 	 * This is the default implementation for formatting the list of includes,
-	 * and prefixes the includes with -I. For compilers like MSVC that require
-	 * different symbols, override this method in your configuration block.
+	 * and prefixes the includes with {@code -I}. For compilers like MSVC that
+	 * require different formatting, the script should supply an overriding
+	 * implementation of this method.
 	 */
 	public List<String> formatIncludes(List<String> includesList)
 	{
@@ -56,12 +82,13 @@ public List<String> formatIncludes(List<String> includesList)
 	}
 
 	/**
-	 * Returns a list with all defines prefixed correctly.
+	 * Returns a list with all defines represented correctly.
 	 *
-	 * This is the default implementation for formatting the list of defines.
-	 * Each item is prefixed with -D. If the define is associated with a value,
-	 * adds equal symbol also followed by the value. If your linker expects a
-	 * different format, override the method in your configuration block.
+	 * This is the default implementation for formatting the map of defines.
+	 * Each item is prefixed with {@code -D}. If the name is mapped to a
+	 * non-null value, an {@code =} is appended, followed by the value. For
+	 * compilers like MSVC that require different formatting, the script should
+	 * supply an overriding implementation of this method.
 	 */
 	public List<String> formatDefines(Map<String, String> definesMap)
 	{
@@ -76,11 +103,11 @@ public List<String> formatDefines(Map<String, String> definesMap)
 	}
 
 	/**
-	 * Returns the input pg_config property as a list of individual flags split
-	 * at whitespace, except when quoted, and the quotes removed.
+	 * Returns the requested {@code pg_config} property as a list of individual
+	 * flags split at whitespace, except when quoted, and the quotes removed.
 	 *<p>
 	 * The assumed quoting convention is single straight quotes around regions
-	 * to be protected, which do not have to be the entire argument. This method
+	 * to be protected, which do not have to be an entire argument. This method
 	 * doesn't handle a value that <em>contains</em> a single quote as content;
 	 * the intended convention for that case doesn't seem to be documented, and
 	 * PostgreSQL's own build breaks in such a case, so there is little need,