Correct formatting of usage helpers for undocumented.

Author: Yaytay

src/main/java/uk/co/spudsoft/params4j/ConfigurationProperty.java

@@ -225,22 +225,35 @@ public boolean equals(Object obj) {
    * 
    */
   public void appendUsage(StringBuilder builder, int maxNameLen) {
-      builder.append("    ")
-              .append(name)
-              .append(" ".repeat(maxNameLen + 1 - name.length()))
-              .append(comment)
-              .append('\n');
+    
+    maxNameLen += 6;
+    
+    builder.append("    ")
+            .append(name);
+    if (undocumented) {
+      builder.append(".<***>");
+    }
+    builder.append(" ".repeat(maxNameLen + 1 - name.length() - (undocumented ? 6 : 0)))
+            .append(comment)            
+            .append('\n');
 
-      String typeName = type.getSimpleName();
-      builder.append("        ")
-              .append(typeName);
+    String typeName = type.getSimpleName();
+    builder.append("        ")
+            .append(typeName);
+
+    if (defaultValue != null) {
+      builder.append(" ".repeat(typeName.length() + 10 > maxNameLen ? 1 : maxNameLen - typeName.length() - 3))
+              .append("default: ")
+              .append(defaultValue);
+    }
+    if (undocumented) {
+      builder.append(" ".repeat(typeName.length() + 10 > maxNameLen ? 1 : maxNameLen - typeName.length() - 3))
+              .append("This parameter is undocumented, consult the source for ")
+              .append(type)
+              .append(" for details of the values for <***>");
 
-      if (defaultValue != null) {
-        builder.append(" ".repeat(typeName.length() + 4 > maxNameLen ? 1 : maxNameLen - typeName.length() - 3))
-                .append("default: ")
-                .append(defaultValue);
-      }
-      builder.append('\n');
+    }
+    builder.append("\n\n");
   }
 
   /**
@@ -266,7 +279,7 @@ public void appendEnv(StringBuilder builder, int maxNameLen, String prefixStrip,
         prefixAdd = "";
       }
 
-      maxNameLen = maxNameLen - prefixStrip.length() + prefixAdd.length() + 1;
+      maxNameLen = maxNameLen - prefixStrip.length() + prefixAdd.length() + 7;
 
       String envVarName = name;
       if (envVarName.startsWith(prefixStrip)) {
@@ -279,21 +292,33 @@ public void appendEnv(StringBuilder builder, int maxNameLen, String prefixStrip,
       envVarName = envVarName.toUpperCase(Locale.ROOT);
 
       builder.append("    ")
-              .append(envVarName)
-              .append(" ".repeat(maxNameLen + 1 - envVarName.length()))
+              .append(envVarName);
+      if (undocumented) {
+        builder.append("_<***>");
+      }
+      builder.append(" ".repeat(maxNameLen + 1 - envVarName.length() - (undocumented ? 6 : 0)))
               .append(comment)
               .append('\n');
 
       String typeName = type.getSimpleName();
       builder.append("        ")
               .append(typeName);
-      
+            
       if (defaultValue != null) {
-        builder.append(" ".repeat(typeName.length() + 4 > maxNameLen ? 1 : maxNameLen - typeName.length() - 3))
+        builder.append(" ".repeat(typeName.length() + 10 > maxNameLen ? 1 : maxNameLen - typeName.length() - 3))
                 .append("default: ")
                 .append(defaultValue);
       }
-      builder.append('\n');
+      
+      if (undocumented) {
+        builder.append(" ".repeat(typeName.length() + 10 > maxNameLen ? 1 : maxNameLen - typeName.length() - 3))
+                .append("This parameter is undocumented, consult the source for ")
+                .append(type)
+                .append(" for details of the values for <***>");
+
+      }
+      
+      builder.append("\n\n");
     }
   }
 

src/main/java/uk/co/spudsoft/params4j/Params4J.java

@@ -60,7 +60,11 @@ static <P> Params4JFactory<P> factory() {
    * @param defaultInstance An instance of the class to be examined, preloaded with default values.
    * @param prefix The prefix to be prepended to any determined property names to match the prefix specified in (for example) the CommandLineArgumentsGatherer.
    * @param terminalClasses List of regular expressions used to identify properties that are of terminal types - if the class is terminal it should be settable by Jackson from a single string value.
+   * Examples of built-in terminal classes include java.time.LocalDateTime and java.time.Duration.
+   * Terminal classes are documented, but their internals are not.
    * @param undocumentedClasses List of regular expressions used to identify properties that are of undocumented types - if the class is undocumented it will not be traversed further despite not being settable by Jackson.
+   * Undocumented classes cannot be set directly and their internal properties are not output in generated documentation (usually because they haven't been processed by the JavadocCapturer).
+   * There are no built-in undocumented classes, but a typical example of a class that should be undocumented is VertxOptions.
    * @return A list of properties that can be set.
    */
   List<ConfigurationProperty> getDocumentation(P defaultInstance, String prefix, List<Pattern> terminalClasses, List<Pattern> undocumentedClasses);

src/main/java/uk/co/spudsoft/params4j/impl/Params4JImpl.java

@@ -259,15 +259,7 @@ private void changeNotificationHandler() {
     }
   }
 
-  private static boolean canBeEnvVar(String propName, Class<?> type, boolean undocumented) {
-    logger.debug("{}/{}/{}", propName, type.getPackageName(), undocumented);
-    if (type.isArray()) {
-      return false;
-    }
-    if (undocumented) {
-      String packageName = type.getPackageName();
-      return "java.time".equals(packageName);
-    }
+  private static boolean canBeEnvVar(String propName) {
     if (propName.contains("[") || propName.contains("]")) {
       return false;
     }
@@ -514,7 +506,7 @@ private void outputTerminalField(
       }
     }
     ConfigurationProperty prop = ConfigurationProperty.builder()
-            .canBeEnvVar(canBeEnvVar(propName, type, undocumented))
+            .canBeEnvVar(canBeEnvVar(propName))
             .undocumented(undocumented)
             .comment(comment)
             .defaultValue(defaultValue == null ? null : defaultValue.toString())

src/test/resources/commentcap-expected.json

@@ -23,14 +23,14 @@
   }, {
     "type": "uk.co.spudsoft.params4j.impl.HtmlAnchorElement",
     "name": "--alien",
-    "canBeEnvVar": false,
+    "canBeEnvVar": true,
     "undocumented": true,
     "comment": "alien value that cannot be documented further in this codebase",
     "defaultValue": null
   }, {
     "type": "uk.co.spudsoft.params4j.impl.HtmlAnchorElement",
     "name": "--documentedAlien",
-    "canBeEnvVar": false,
+    "canBeEnvVar": true,
     "undocumented": true,
     "comment": "configure the alien properties as documented at https://docs.oracle.com/en/java/javase/17/docs/api/jdk.xml.dom/org/w3c/dom/html/HTMLAnchorElement.html",
     "defaultValue": null