Docgen tweaks

* When emitting default values, format as "Default: <value>"
* When default is "", emit as "<unspecified>"
* Add link to hocon wiki page when referencing HOCON.

Author: stamhankar999

engine/src/main/java/com/datastax/dsbulk/engine/internal/OptionUtils.java

@@ -115,7 +115,11 @@ private static String getSanitizedDescription(String longName, ConfigValue value
     //   Those sorts of instances are preceded by ", so don't replace those.
 
     desc = desc.replaceAll(" +", " ").replaceAll("([^\"])\\*\\*", "$1").trim();
-    desc += "\nDefaults to " + value.render(ConfigRenderOptions.concise()) + ".";
+    String defaultValue = value.render(ConfigRenderOptions.concise());
+    if (defaultValue.equals("\"\"")) {
+      defaultValue = "<unspecified>";
+    }
+    desc += "\nDefault: " + defaultValue;
     return desc;
   }
 }

engine/src/main/java/com/datastax/dsbulk/engine/internal/SettingsDocumentor.java

@@ -257,10 +257,11 @@ private static String getSanitizedDescription(ConfigValue value) {
             .map(s -> s.length() > 0 ? s.substring(1) : s)
             .collect(Collectors.joining("\n"));
     if (value.valueType() != ConfigValueType.OBJECT) {
-      desc +=
-          String.format(
-              "%n%nDefaults to **%s**.",
-              value.render(ConfigRenderOptions.concise()).replace("*", "\\*"));
+      String defaultValue = value.render(ConfigRenderOptions.concise()).replace("*", "\\*");
+      if (defaultValue.equals("\"\"")) {
+        defaultValue = "<unspecified>";
+      }
+      desc += String.format("%n%nDefault: **%s**.", defaultValue);
     }
     return desc;
   }

engine/src/main/resources/reference.conf

@@ -545,7 +545,7 @@ dsbulk {
     #
     # In unload workflows, only the first string specified here will be used: when a row cell contains a `null` value, then it will be replaced with that word and forwarded as such to the connector.
     #
-    # The default value – `""` – means that in load workflows, empty strings are converted to `null`s, and in unload workflows, `null`s are converted to empty strings.
+    # By default, empty strings are converted to `null`s in load workflows, and conversely `null`s are converted to empty strings in unload workflows.
     nullStrings: ""
 
     # Whether or not to map `null` input values to "unset" in the database, meaning don't modify a potentially pre-existing value of this field for this row.
@@ -563,7 +563,7 @@ dsbulk {
     #
     # If not specified, the loader will apply a strict one-to-one mapping between the source fields and the database table. If that is not what you want, then you must supply an explicit mapping.
     #
-    # Mappings should be specified as a HOCON map of the following form:
+    # Mappings should be specified as a HOCON map (https://github.com/typesafehub/config/blob/master/HOCON.md) of the following form:
     #
     # - Indexed data sources: `0 = col1, 1 = col2, 2 = col3`, where `0`, `1`, `2`, etc. are the zero-based indices of fields in the source data; and `col1`, `col2`, `col3` are bound variable names in the insert statement.
     # - Mapped data sources: `fieldA = col1, fieldB = col2, fieldC = col3`, where `fieldA`, `fieldB`, `fieldC`, etc. are field names in the source data; and `col1`, `col2`, `col3` are bound variable names in the insert statement.
@@ -582,7 +582,7 @@ dsbulk {
     # - If the connector is capable of reporting the record metadata accurately (for example, some database connectors might be able to inspect the target table's metadata), then this section is only required if you want to override some field types as reported by the connector.
     # - If the connector is not capable of reporting the record metadata accurately (for example, file connectors usually cannot report such information), then all fields are assumed to be of type `String`. If this is not correct, then you need to provide the correct type information here.
     #
-    # Field metadata should be specified as a HOCON map of the following form:
+    # Field metadata should be specified as a HOCON map (https://github.com/typesafehub/config/blob/master/HOCON.md) of the following form:
     #
     # - Indexed data sources: `0 = java.lang.String, 1 = java.lang.Double`, where `0`, `1`, etc. are the zero-based indices of fields in the source data; and the values are the expected types for each field.
     # - Mapped data sources: `fieldA = java.lang.String, fieldB = java.lang.Double`, where `fieldA`, `fieldB`, etc. are field names in the source data; and the values are the expected types for each field.