[Feature Request]: Enable display of @Description annotations in generated Javadocs

[slilichenko]

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

[lukecwik]

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 ?

[slilichenko]

Yes, that's the idea - have a single source of truth and have it visible.

[lukecwik]

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

[slilichenko]

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.

[Abacn]

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