Open devinrsmith opened 1 month ago
I'll note: consumers of objects may be best served by documentation on the object methods, and producers of objects may be best served by documentation on the builder methods.
My general preference is to reduce duplication of documentation by providing {@link ...}
where appropriate, in the spirit of reducing the chance of drift (somebody updates documentation on an object method but forgets to update the documentation on the builder method, or vice versa).
Also, see original comments from https://github.com/deephaven/deephaven-core/pull/5752/files#r1706006738
Currently, the majority of our https://immutables.github.io/ builders don't have any javadoc; we (mostly) document the getter properties of the objects to be constructed.
As a simplified / abbreviated example:
From the javadoc on the object's class, users might be able to infer the meaning and optionality of
Builder#host
,Builder#port
, andBuilder#shutdownTimeout
.Some options:
{@link ...}
from builder methods to object methods{@link ...}
from object methods to builder methods{@link ...}
from the generated code. As an example, here is what the auto-generated javadoc from immutables looks like: