chore: Improve javadoc generation

docs/maintainers/todo.md

@@ -25,8 +25,23 @@
 - [ ] Release python
 - [ ] Release C# ?
 
+## Permalinks needed
+
+The following links need to be made permanent, or replaced with permalink
+versions, as they are listed in source code / generated documentation.
+
+- https://case.contract-testing.io/docs/reference/configuring
+- https://case.contract-testing.io/docs/reference/state-handlers/
+- https://case.contract-testing.io/docs/reference/triggers
+
 ## Todo list
 
+Java:
+
+- Give `TriggerGroups` a builder and make it immutable, to match the rest of the builders
+- Complete javadoc (eliminate all warnings)
+- Autogenerate documentation or configuration classes somehow - so that they're in sync between different languages
+
 Next:
 
 - [ ] Configuration Errors in triggers are incorrectly mapped to verification failures

packages/dsl-java/build.gradle

@@ -18,16 +18,23 @@ repositories {
     mavenLocal()
 }
 
+tasks.withType(Javadoc).configureEach {
+    exclude('io/contract_testing/contractcase/grpc')
+    exclude('io/contract_testing/contractcase/edge')
+    exclude('io/contract_testing/contractcase/client')
+}
+
 def caseCoreVersion = "0.15.6"
 def grpcVersion = "1.68.0"
+def protobufVersion = "4.28.2"
 
 dependencies {
     api "io.contract-testing.contractcase:case_example_mock_types:${caseCoreVersion}"
     api "io.contract-testing.contractcase:test-equivalence-matchers:${caseCoreVersion}"
     implementation 'com.diogonunes:JColor:5.5.1'
-    implementation 'com.google.protobuf:protobuf-java:4.28.2'
-    implementation 'com.google.protobuf:protobuf-java-util:4.28.2'
-    implementation 'com.google.protobuf:protoc:4.28.2'
+    implementation "com.google.protobuf:protobuf-java:${protobufVersion}"
+    implementation "com.google.protobuf:protobuf-java-util:${protobufVersion}"
+    implementation "com.google.protobuf:protoc:${protobufVersion}"
     implementation "io.grpc:protoc-gen-grpc-java:${grpcVersion}"
     implementation "io.grpc:grpc-core:${grpcVersion}"
     implementation "io.grpc:grpc-stub:${grpcVersion}"
@@ -84,12 +91,12 @@ protobuf {
         // If you don't specify it, protoc will try to use "protoc-gen-grpc" from
         // system search path.
         'grpc' {
-            artifact = 'io.grpc:protoc-gen-grpc-java:1.68.0'
+            artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}"
         }
     }
     protoc {
         // Download from repositories
-        artifact = 'com.google.protobuf:protoc:4.28.2'
+        artifact = "com.google.protobuf:protoc:${protobufVersion}"
     }
     generateProtoTasks {
         all().configureEach { task ->
@@ -102,9 +109,7 @@ protobuf {
                 }
             }
         }
-
     }
-
 }
 
 

packages/dsl-java/src/main/java/io/contract_testing/contractcase/ContractCaseConfig.java

@@ -4,7 +4,12 @@
 import java.util.Map;
 
 /**
- * Config object for ContractCase
+ * Config object for ContractCase. See the <a
+ * href="https://case.contract-testing.io/docs/reference/configuring">configuration reference</a>
+ * for more details.
+ *
+ * @see <a href="https://case.contract-testing.io/docs/reference/configuring">Configuration
+ * reference</a>
  */
 public class ContractCaseConfig {
 
@@ -95,16 +100,27 @@ public class ContractCaseConfig {
    */
   public final Map<String, Map<String, String>> mockConfig;
 
-
+  /**
+   * Define the trigger and test function (if any) for this interaction pair.
+   * <p>
+   * See <a href="https://case.contract-testing.io/docs/reference/triggers">the trigger
+   * reference</a> and {@link TriggerGroups} for details.
+   */
   public final TriggerGroups triggers;
 
   /**
-   * State setup and teardown handlers for any states this test requires (see (<a
-   * href="https://case.contract-testing.io/docs/reference/state-handlers/">writing state
-   * handlers</a>)) for more details
+   * State setup and teardown handlers for any states this test requires.
+   * <p>
+   * See <a href="https://case.contract-testing.io/docs/reference/state-handlers/">writing state
+   * handlers</a> for more details
    */
   public final Map<String, StateHandler> stateHandlers;
 
+  /**
+   * Don't construct this directly, use a {@link ContractCaseConfigBuilder} instead, obtained via
+   * {@link ContractCaseConfigBuilder#aContractCaseConfig()}
+   */
+  @SuppressWarnings("doclint")
   protected ContractCaseConfig(String providerName, String consumerName, LogLevel logLevel,
       String contractDir, String contractFilename, Boolean printResults, Boolean throwOnFail,
       PublishType publish, String brokerBaseUrl, String brokerCiAccessToken,
@@ -183,6 +199,14 @@ public Map<String, StateHandler> getStateHandlers() {
     return stateHandlers;
   }
 
+  /**
+   * Builder for {@link ContractCaseConfig} objects.
+   * <p>
+   * See the documentation for {@link ContractCaseConfig} for java specifics, and the
+   * <a href="https://case.contract-testing.io/docs/reference/configuring">configuration
+   * reference</a> for full details.
+   */
+  @SuppressWarnings("doclint")
   public static final class ContractCaseConfigBuilder {
 
     private String providerName;
@@ -205,6 +229,9 @@ public static final class ContractCaseConfigBuilder {
     private ContractCaseConfigBuilder() {
     }
 
+    /**
+     * @return An empty builder
+     */
     public static ContractCaseConfigBuilder aContractCaseConfig() {
       return new ContractCaseConfigBuilder();
     }