Gen/javadoc

pom.xml

@@ -22,12 +22,12 @@
     <parent>
         <groupId>net.openhft</groupId>
         <artifactId>java-parent-pom</artifactId>
-        <version>1.24.0</version>
+        <version>1.25.4</version>
         <relativePath />
     </parent>
 
     <artifactId>chronicle-wire</artifactId>
-    <version>2.25ea6-SNAPSHOT</version>
+    <version>2.25ea11-SNAPSHOT</version>
     <name>OpenHFT/Chronicle-Wire</name>
     <description>Chronicle-Wire</description>
     <packaging>bundle</packaging>
@@ -38,14 +38,20 @@
         <compiler.argument>-Xlint:deprecation</compiler.argument>
         <sonar.organization>openhft</sonar.organization>
         <sonar.host.url>https://sonarcloud.io</sonar.host.url>
+        <!-- The parent POM defines this plugin and activates it in a profile. Unfortunately this plugin will generate
+        code at @NotNull call-sites that throws IllegalArgumentException rather than NullPointerException. This will
+        break various core tests. Chronicle have raised this issue before with the maintainers of the plugin. See:
+        https://github.com/osundblad/intellij-annotations-instrumenter-maven-plugin/issues/53
+        -->
+        <se.eris.notnull.instrument>false</se.eris.notnull.instrument>
     </properties>
 
     <dependencyManagement>
         <dependencies>
             <dependency>
                 <groupId>net.openhft</groupId>
                 <artifactId>third-party-bom</artifactId>
-                <version>3.24.0</version>
+                <version>3.25.0</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
@@ -192,7 +198,7 @@
                         <configuration>
                             <referenceVersion>2.25ea0</referenceVersion>
                             <artifactsURI>https://teamcity.chronicle.software/repository/download</artifactsURI>
-                            <binaryCompatibilityPercentageRequired>99.9</binaryCompatibilityPercentageRequired>
+                            <binaryCompatibilityPercentageRequired>99.6</binaryCompatibilityPercentageRequired>
                             <extraOptions>
                                 <extraOption>
                                     <name>skip-internal-packages</name>
@@ -208,6 +214,7 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
                 <configuration>
+                    <!-- required for Issue327Test.date -->
                     <systemPropertyVariables>
                         <user.timezone>UTC</user.timezone>
                     </systemPropertyVariables>

src/main/java/net/openhft/chronicle/wire/AbstractAnyWire.java

@@ -30,28 +30,45 @@
 import java.util.function.Supplier;
 
 /**
- * A wire type than can be either
- * <p>
- * TextWire BinaryWire
+ * An abstract representation of a wire type that could be either {@code TextWire} or {@code BinaryWire}.
+ * This class provides a generic foundation for wire types that could shift between the two mentioned types
+ * based on the underlying acquisition logic.
  *
  * @author Rob Austin.
  */
 @SuppressWarnings("rawtypes")
 public abstract class AbstractAnyWire extends AbstractWire implements Wire {
 
     @NotNull
-    protected final WireAcquisition wireAcquisition;
-
+    protected final WireAcquisition wireAcquisition;  // Responsible for acquiring the actual wire type (TextWire or BinaryWire).
+
+    /**
+     * Constructs a new instance of {@code AbstractAnyWire} using the specified bytes and wire acquisition strategy.
+     *
+     * @param bytes The byte storage and manipulation object.
+     * @param wa    The strategy to acquire the actual wire type.
+     */
     protected AbstractAnyWire(@NotNull Bytes<?> bytes, @NotNull WireAcquisition wa) {
         super(bytes, false);
         this.wireAcquisition = wa;
     }
 
+    /**
+     * Retrieves the underlying wire, which could be either {@code TextWire} or {@code BinaryWire},
+     * based on the acquisition strategy.
+     *
+     * @return The underlying wire type.
+     */
     @Nullable
     public Wire underlyingWire() {
         return wireAcquisition.acquireWire();
     }
 
+    /**
+     * Provides a supplier that indicates the type of the underlying wire.
+     *
+     * @return A supplier yielding the {@code WireType}.
+     */
     @NotNull
     public Supplier<WireType> underlyingType() {
         return wireAcquisition.underlyingType();
@@ -208,19 +225,39 @@ public String readingPeekYaml() {
         return wireAcquisition.acquireWire().readingPeekYaml();
     }
 
+    /**
+     * Represents an interface defining the strategy for acquiring and interacting with the underlying wire types.
+     */
     interface WireAcquisition {
 
         /**
-         * @return the type of wire for example Text or Binary
+         * Provides a supplier indicating the type of the underlying wire, which could be either {@code TextWire} or {@code BinaryWire}.
+         *
+         * @return A supplier yielding the {@code WireType}.
          */
         @NotNull
         Supplier<WireType> underlyingType();
 
+        /**
+         * Retrieves the actual wire type which could be either {@code TextWire} or {@code BinaryWire}.
+         *
+         * @return The acquired wire type.
+         */
         @Nullable
         Wire acquireWire();
 
+        /**
+         * Sets the class lookup mechanism for this wire acquisition.
+         *
+         * @param classLookup The class lookup mechanism to set.
+         */
         void classLookup(ClassLookup classLookup);
 
+        /**
+         * Retrieves the class lookup mechanism associated with this wire acquisition.
+         *
+         * @return The class lookup mechanism.
+         */
         @Nullable
         ClassLookup classLookup();
     }