You are viewing a plain text version of this content. The canonical link for it is here.
Posted to common-issues@hadoop.apache.org by "Daniel Carl Jones (Jira)" <ji...@apache.org> on 2022/04/27 09:53:00 UTC
[jira] [Comment Edited] (HADOOP-18187) Convert s3a prefetching to use JavaDoc for fields and enums
[ 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-unsubscribe@hadoop.apache.org
For additional commands, e-mail: common-issues-help@hadoop.apache.org