Expand internals javadoc to package types/members

The earlier work fixing run-busting errors in javadoc comments permits
the javadoc coverage for the o.p.p.internal module to be expanded to
cover package-private types and members.

In passing, add enough missing class-level javadoc comments to make
the resulting package listings somewhat presentable.

Author: jcflack

pljava/pom.xml

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

pljava/src/main/java/org/postgresql/pljava/internal/AbstractNoSplitList.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2023-2025 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
@@ -54,6 +54,9 @@ public Spliterator<E> spliterator()
 		return new IteratorNonSpliterator<>(iterator(), size(), ORDERED|SIZED);
 	}
 
+	/**
+	 * As promised, an iterator whose spliterator won't split.
+	 */
 	public static class IteratorNonSpliterator<E> extends AbstractSpliterator<E>
 	{
 		private Iterator<E> it;

pljava/src/main/java/org/postgresql/pljava/internal/CacheMap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2022-2025 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
@@ -31,6 +31,11 @@
 
 import static java.util.stream.Collectors.joining;
 
+/**
+ * Utility class for constructing caches that map from keys that consist of
+ * one or more primitive values, whose entries can be retained strongly, softly,
+ * or weakly.
+ */
 public class CacheMap<T>
 {
 	private final Map<ByteBuffer,KeyedEntry<T>> m_map;
@@ -198,17 +203,27 @@ public void forEachValue(Consumer<T> action)
 			.forEach(action);
 	}
 
+	/**
+	 * An entry in a {@link CacheMap CacheMap}.
+	 */
 	public interface Entry<T>
 	{
 		T get();
 		void remove();
 	}
 
+	/**
+	 * An {@link Entry Entry} that keeps a reference to its key.
+	 */
 	interface KeyedEntry<T> extends Entry<T>
 	{
 		ByteBuffer key();
 	}
 
+	/**
+	 * A {@link KeyedEntry KeyedEntry} that holds
+	 * a {@link SoftReference SoftReference} to its value.
+	 */
 	static class SoftEntry<T> extends SoftReference<T> implements KeyedEntry<T>
 	{
 		final ByteBuffer m_key;
@@ -233,6 +248,10 @@ public void remove()
 		}
 	}
 
+	/**
+	 * A {@link KeyedEntry KeyedEntry} that holds
+	 * a {@link WeakReference WeakReference} to its value.
+	 */
 	static class WeakEntry<T> extends WeakReference<T> implements KeyedEntry<T>
 	{
 		final ByteBuffer m_key;
@@ -257,6 +276,10 @@ public void remove()
 		}
 	}
 
+	/**
+	 * A {@link KeyedEntry KeyedEntry} that holds
+	 * a strong reference to its value.
+	 */
 	static class StrongEntry<T> implements KeyedEntry<T>
 	{
 		final ByteBuffer m_key;
@@ -295,6 +318,15 @@ public void remove()
 	 * construction and return (to avoid any chance of its being found
 	 * weakly reachable before its return).
 	 */
+	/**
+	 * An effectively private class used during {@link CacheMap CacheMap}
+	 * operations.
+	 *<p>
+	 * Until PL/Java's support horizon for Java moves to Java >= 11 where
+	 * classes have nestmates, there can be overhead in making nested classes
+	 * private, so some in the internal module have been left at package access
+	 * for now.
+	 */
 	static class KVHolder<T>
 	{
 		ByteBuffer key;

pljava/src/main/java/org/postgresql/pljava/internal/ExecutionPlan.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004-2022 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2004-2025 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
@@ -145,6 +145,10 @@ protected boolean removeEldestEntry(
 		}
 	};
 
+	/**
+	 * The actual (but treated as opaque {@code Object} key used in the plan
+	 * cache.
+	 */
 	static final class PlanKey
 	{
 		private final int m_hashCode;

pljava/src/main/java/org/postgresql/pljava/internal/LifespanImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2022-2025 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
@@ -32,6 +32,11 @@
  */
 public class LifespanImpl extends DualState.ListHead implements Lifespan
 {
+	/**
+	 * Interface to be additionally implemented by
+	 * a {@link LifespanImpl LifespanImpl} with an associated native address
+	 * that may be needed during release handling.
+	 */
 	public interface Addressed
 	{
 		long address();

pljava/src/main/java/org/postgresql/pljava/internal/SQL_ASCII.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2021 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2020-2025 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
@@ -54,13 +54,19 @@
  */
 class SQL_ASCII extends Charset
 {
+	/**
+	 * Holder class for list of provided {@link Charset Charset}s.
+	 */
 	static class Holder
 	{
 		static final List<Charset> s_list =
 			singletonList((Charset)new SQL_ASCII());
 	}
 
 
+	/**
+	 * Provider for {@link Charset Charset} discovery.
+	 */
 	public static class Provider extends CharsetProvider
 	{
 		static final String s_canonName = "X-PGSQL_ASCII";
@@ -109,6 +115,9 @@ public CharsetEncoder newEncoder()
 	}
 
 
+	/**
+	 * Decoder for {@link SQL_ASCII SQL_ASCII}.
+	 */
 	static class Decoder extends CharsetDecoder
 	{
 		Decoder()
@@ -156,6 +165,9 @@ protected CoderResult decodeLoop(ByteBuffer in, CharBuffer out)
 		}
 	}
 
+	/**
+	 * Encoder for {@link SQL_ASCII SQL_ASCII}.
+	 */
 	static class Encoder extends CharsetEncoder
 	{
 		Encoder()

pljava/src/main/java/org/postgresql/pljava/internal/SyntheticXMLReader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2019-2025 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
@@ -103,6 +103,9 @@ public abstract class SyntheticXMLReader implements XMLReader
 	 */
 	public final FluentAttributes2 m_attributes = new FluentAttributes2();
 
+	/**
+	 * Enumeration of features standardized by SAX 2.
+	 */
 	public enum SAX2FEATURE
 	{
 		EXTERNAL_GENERAL_ENTITIES("external-general-entities", null),
@@ -184,6 +187,9 @@ public static SAX2FEATURE fromUri(String uri)
 		}
 	}
 
+	/**
+	 * Enumeration of features originating with Apache.
+	 */
 	public enum ApacheFeature
 	{
 		DISALLOW_DOCTYPE_DECL("disallow-doctype-decl", false),
@@ -237,6 +243,9 @@ public static ApacheFeature fromUri(String uri)
 		}
 	}
 
+	/**
+	 * Enumeration of properties standardized by SAX 2.
+	 */
 	public enum SAX2PROPERTY
 	{
 		DECLARATION_HANDLER("declaration-handler", DeclHandler.class),

pljava/src/main/java/org/postgresql/pljava/pg/AccessMethodImpl.java

@@ -37,6 +37,9 @@
 
 import static org.postgresql.pljava.internal.UncheckedException.unchecked;
 
+/**
+ * Implementation of the {@link AccessMethod AccessMethod} interface.
+ */
 class AccessMethodImpl extends Addressed<AccessMethod>
 implements Nonshared<AccessMethod>, Named<Simple>, AccessMethod
 {

pljava/src/main/java/org/postgresql/pljava/pg/AclItem.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022-2023 Tada AB and other contributors, as listed below.
+ * Copyright (c) 2022-2025 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
@@ -29,6 +29,9 @@
 import static org.postgresql.pljava.pg.ModelConstants.N_ACL_RIGHTS;
 import static org.postgresql.pljava.pg.ModelConstants.PG_VERSION_NUM;
 
+/**
+ * Implementation of the {@link CatalogObject.Grant Grant} interface.
+ */
 public abstract class AclItem implements CatalogObject.Grant
 {
 	/*

pljava/src/main/java/org/postgresql/pljava/pg/AttributeImpl.java

@@ -53,6 +53,9 @@
 
 import static org.postgresql.pljava.internal.UncheckedException.unchecked;
 
+/**
+ * Implementation of the {@link Attribute Attribute} interface.
+ */
 abstract class AttributeImpl extends Addressed<RegClass>
 implements
 	Nonshared<RegClass>, Named<Simple>,