apache
[Feature Request]: Enable display of @Description annotations in generated Javadocs
What would you like to happen?
*Option classes contain @Description annotations which contain the details about the given option. But these annotations are no displayed in the generated Javadoc leading to poorly documented classes.
Issue Priority
Priority: 2
Issue Component
Component: release
Would this have us consolidate and remove the current javadocs that appear twice like in https://github.com/apache/beam/blob/c54082f291a7f718ddc2aa95f7e17f24c49a1c71/sdks/java/core/src/main/java/org/apache/beam/sdk/options/SdkHarnessOptions.java#L75 ?
Yes, that's the idea - have a single source of truth and have it visible.
The textual representations used in @Description will limit what we can display to the user since there are places where we need to format it so that it displays correctly as javadoc. Take a look at a few of the differences in SdkHarnessOptions.java like https://github.com/apache/beam/blob/e6e832b62ec2b1f1ef5214fd4174d1362d444dce/sdks/java/core/src/main/java/org/apache/beam/sdk/options/SdkHarnessOptions.java#L91
Yes, I saw them. You also have cases like BigQueryOptions, which has no JavaDoc, but uses JavaDoc style in @Description. Perhaps that can be a middle ground, admittedly imperfect. Also, I am not sure that customers really use ./run-pipeline.sh --help=SomeSDKOptionClass to get information about an option. It would be a Google or code search, at least IMHO.
I tried to add "@Documented" to "@Description". The javadoc now contains the description, but the rendering is overflow for long description:
Searched around and this seems not trivial
