[GitHub] [kafka] showuon commented on a diff in pull request #13710: MINOR: Fix the outdated comments of ConfigDef

["showuon (via GitHub)" <gi...@apache.org>]

showuon commented on code in PR #13710:
URL: https://github.com/apache/kafka/pull/13710#discussion_r1198513990


##########
clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java:
##########
@@ -68,8 +68,8 @@
  * int anotherConfig = (Integer) configs.get("config_with_validator");
  *
  * To validate the full configuration, use:

Review Comment:
   Should this line be commented? i.e. 
   `// To validate the full configuration, use:`



##########
clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java:
##########
@@ -68,8 +68,8 @@
  * int anotherConfig = (Integer) configs.get("config_with_validator");
  *
  * To validate the full configuration, use:
- * List<Config> configs = defs.validate(props);
- * The {@link Config} contains updated configuration information given the current configuration values.
+ * List<ConfigValue> configValues = defs.validate(props);
+ * The {@link ConfigValue} contains updated configuration information given the current configuration values.

Review Comment:
   Same here. This should be commented:
   `// The {@link ConfigValue} contains updated configuration information given the current configuration values.`



##########
clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java:
##########
@@ -53,9 +53,9 @@
  * <pre>
  * ConfigDef defs = new ConfigDef();
  *
- * defs.define(&quot;config_with_default&quot;, Type.STRING, &quot;default string value&quot;, &quot;Configuration with default value.&quot;);
- * defs.define(&quot;config_with_validator&quot;, Type.INT, 42, Range.atLeast(0), &quot;Configuration with user provided validator.&quot;);
- * defs.define(&quot;config_with_dependents&quot;, Type.INT, &quot;Configuration with dependents.&quot;, &quot;group&quot;, 1, &quot;Config With Dependents&quot;, Arrays.asList(&quot;config_with_default&quot;,&quot;config_with_validator&quot;));
+ * defs.define(&quot;config_with_default&quot;, Type.STRING, &quot;default string value&quot;, Importance.High, &quot;Configuration with default value.&quot;);
+ * defs.define(&quot;config_with_validator&quot;, Type.INT, 42, Range.atLeast(0), Importance.High, &quot;Configuration with user provided validator.&quot;);
+ * defs.define(&quot;config_with_dependents&quot;, Type.INT, Importance.LOW, &quot;Configuration with dependents.&quot;, &quot;group&quot;, 1, Width.SHORT, &quot;Config With Dependents&quot;, Arrays.asList(&quot;config_with_default&quot;,&quot;config_with_validator&quot;));

Review Comment:
   Thanks for the update. Could we add a link to the original method java doc, so that users will be more clear what it means for each parameter. Ex: 
   ```
   * // check {@link #define(String, Type, Object, Importance, String) for more detail}
   * defs.define(&quot;config_with_default&quot;, Type.STRING, &quot;default string value&quot;, 
   Importance.High, &quot;Configuration with default value.&quot;);
   * // check {@link #define.....} 
   * defs.define(&quot;config_with_validator&quot;, Type.INT, 42, Range.atLeast(0), Importance.High, &quot;Configuration with user provided validator.&quot;);
   ```
   
   WDYT?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org