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

[via GitHub]

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-unsubscr...@kafka.apache.org

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