[ https://issues.apache.org/jira/browse/HADOOP-18187?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17528611#comment-17528611 ]
Daniel Carl Jones edited comment on HADOOP-18187 at 4/27/22 9:52 AM: --------------------------------------------------------------------- Here's an example of a file with good JavaDoc. [https://github.com/apache/hadoop/blob/60cb6b5743c67dedc3f6575621d6a150ebc0761f/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/impl/OpenFileSupport.java] The main goal for this task is to move a lot of non-JavaDoc comments to JavaDoc. There's many instances of good documentation but it won't be picked up by the JavaDoc pages or IDE hints. A few examples... * Class fields like this: [https://github.com/apache/hadoop/commit/342e1cd3fcbd2e7d00ab6a620c8ae4919bbc4201#diff-fa939ca467a01f13835de546620f926f3acd0f0f8730ae8c0960a7238e05fc4aR33-R40] * Enum values like this: [https://github.com/apache/hadoop/commit/342e1cd3fcbd2e7d00ab6a620c8ae4919bbc4201#diff-13d9d8e446f8fc6c5a1f2842ef9629dcd8310519cd6d40cdc26607b91ba609a8R45-R63] * Good comments about class invariants but should be part of the class docs: [https://github.com/apache/hadoop/commit/342e1cd3fcbd2e7d00ab6a620c8ae4919bbc4201#diff-05c34609715bb2a5a20e67e6f70d876f4ebe23ba275dad29cec4b184b552a1adR49-R52] was (Author: JIRAUSER284792): Here's an example of a file with good JavaDoc. [https://github.com/apache/hadoop/blob/60cb6b5743c67dedc3f6575621d6a150ebc0761f/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/impl/OpenFileSupport.java] One of the main goals for this task is to move a lot of non-JavaDoc comments to JavaDoc. There's many instances of good documentation but it won't be picked up by the JavaDoc pages or IDE hints. A few examples... * Class fields like this: [https://github.com/apache/hadoop/commit/342e1cd3fcbd2e7d00ab6a620c8ae4919bbc4201#diff-fa939ca467a01f13835de546620f926f3acd0f0f8730ae8c0960a7238e05fc4aR33-R40] * Enum values like this: [https://github.com/apache/hadoop/commit/342e1cd3fcbd2e7d00ab6a620c8ae4919bbc4201#diff-13d9d8e446f8fc6c5a1f2842ef9629dcd8310519cd6d40cdc26607b91ba609a8R45-R63] * Good comments about class invariants but should be part of the class docs: [https://github.com/apache/hadoop/commit/342e1cd3fcbd2e7d00ab6a620c8ae4919bbc4201#diff-05c34609715bb2a5a20e67e6f70d876f4ebe23ba275dad29cec4b184b552a1adR49-R52] > Convert s3a prefetching to use JavaDoc for fields and enums > ----------------------------------------------------------- > > Key: HADOOP-18187 > URL: https://issues.apache.org/jira/browse/HADOOP-18187 > Project: Hadoop Common > Issue Type: Sub-task > Components: fs/s3 > Affects Versions: 3.4.0 > Reporter: Daniel Carl Jones > Assignee: Bhalchandra Pandit > Priority: Minor > > There's lots of good comments for fields and enum values in the current code. > Let's expose these to your IDE with JavaDoc instead. -- This message was sent by Atlassian Jira (v8.20.7#820007) --------------------------------------------------------------------- To unsubscribe, e-mail: common-issues-unsubscr...@hadoop.apache.org For additional commands, e-mail: common-issues-h...@hadoop.apache.org