You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@beam.apache.org by GitBox <gi...@apache.org> on 2022/11/18 20:18:25 UTC

[GitHub] [beam] slilichenko opened a new issue, #24265: [Feature Request]: Enable display of @Description annotations in generated Javadocs

slilichenko opened a new issue, #24265:
URL: https://github.com/apache/beam/issues/24265

   ### 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


-- 
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: github-unsubscribe@beam.apache.org.apache.org

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

[GitHub] [beam] slilichenko commented on issue #24265: [Feature Request]: Enable display of @Description annotations in generated Javadocs

Posted by GitBox <gi...@apache.org>.
slilichenko commented on issue #24265:
URL: https://github.com/apache/beam/issues/24265#issuecomment-1322672352

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


-- 
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: github-unsubscribe@beam.apache.org

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

[GitHub] [beam] lukecwik commented on issue #24265: [Feature Request]: Enable display of @Description annotations in generated Javadocs

Posted by GitBox <gi...@apache.org>.
lukecwik commented on issue #24265:
URL: https://github.com/apache/beam/issues/24265#issuecomment-1322695289

   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


-- 
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: github-unsubscribe@beam.apache.org

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

[GitHub] [beam] lukecwik commented on issue #24265: [Feature Request]: Enable display of @Description annotations in generated Javadocs

Posted by GitBox <gi...@apache.org>.
lukecwik commented on issue #24265:
URL: https://github.com/apache/beam/issues/24265#issuecomment-1320565092

   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 ?


-- 
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: github-unsubscribe@beam.apache.org

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

[GitHub] [beam] slilichenko commented on issue #24265: [Feature Request]: Enable display of @Description annotations in generated Javadocs

Posted by GitBox <gi...@apache.org>.
slilichenko commented on issue #24265:
URL: https://github.com/apache/beam/issues/24265#issuecomment-1322729983

   Yes, I saw them. You also have cases like
   
   [BigQueryOptions](https://github.com/apache/beam/blob/8df6f67c65b4888c45c31e088fb463972c4ec76b/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryOptions.java), 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.


-- 
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: github-unsubscribe@beam.apache.org

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