Overall, +1 on sticking with key-values for configs.
> Con: The IDE gives nice auto-completion for pojos. > > Con: There are some advantages to javadoc as a documentation mechanism for > java people. Optionally, both the above cons can be addressed (to some degree) by wrapper config POJOs that read in the config. i.e., the client will provide a KV config, but then we (internally) would load that into a specific config POJO that will be helpful for auto-completion and javadocs and convenience for our internal implementation (as opposed to using getLong/getString, etc. which could cause runtime exceptions if done incorrectly). The javadoc in the pojo would need a @value link to the original config key string if it is to show up in the generated javadoc. > show you the value of the constant, just the variable name (unless you > discover how to unhide it). That is fine for the clients, but for the Figuring out a way to un-hide it would be preferable to having to keep the website as the single source of documentation (even if it is generated from the javadoc) and make the javadoc link to it. I tried, but was unsuccessful so unless someone knows how to do that the above approach is the next-best alternative. > server would be very weird especially for non-java people. We could attempt > to duplicate documentation between the javadoc and the ConfigDef but given > our struggle to get well-documented config in a single place this seems > unwise. > > So I recommend we have a single source for documentation of these and that > that source be the website documentation on configuration that covers > clients and server and that that be generated off the config defs. The > javadoc on KafkaProducer will link to this table so it should be quite > convenient to discover.
