Merge feature/REL1_6_STABLE/sodiags into REL1_6_STABLE

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,