You are viewing a plain text version of this content. The canonical link for it is here.
Posted to common-dev@hadoop.apache.org by "Nigel Daley (JIRA)" <ji...@apache.org> on 2006/11/21 23:44:02 UTC
[jira] Created: (HADOOP-742) JobConf needs better javadoc
JobConf needs better javadoc
----------------------------
Key: HADOOP-742
URL: http://issues.apache.org/jira/browse/HADOOP-742
Project: Hadoop
Issue Type: Bug
Affects Versions: 0.8.0
Reporter: Nigel Daley
Priority: Minor
The org.apache.hadoop.mapred.JobConf class needs better javadoc comments.
In general terms, these guidelines should be followed:
- http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide
- document the unchecked exceptions that the caller might reasonably want to catch
- use <code> font appropriately (detailed in link above)
- document default values and appropriate configuration file properties
- comments, tags, links, etc used consistently across API
In particular, the javadoc for this class should at least answer these questions:
- all constructors: what happens if the supplied class, file path, or configuration doesn't exist or is null?
- JobConf() constructor: where are default values loaded from?
- JobConf(Configuration) constructor: indicate that this is effectively a copy constructor
- JobConf(String) constructor: are there any format requirements on the string? local and dfs paths allowed?
- setter methods that take a path: what happens if the path doesn't exist?
- getter methods returning objects: if value has not been set, is null returned or something else?
- are JobConf objects immutable? If not, why not?
- setNum*Tasks: is this per TaskTracker? or something else?
- methods that take a Path: what if the path is relative?
- setWorkingDirectory: is this deleted at the end of a job? should it be local or dfs?
- *KeepFailedTaskFiles: if they are kept, where can they be found?
- *KeepTaskFilesPattern: what does "the files" mean? if they are kept, where can they be found?
- deleteLocalFiles: undoubtedly a risky operation. Need a good spec. Is it a recursive delete?
- which configuration entries are mandatory (i.e. must be set before submitting the job)?
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (HADOOP-742) JobConf needs better javadoc
Posted by "Nigel Daley (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-742?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Nigel Daley updated HADOOP-742:
-------------------------------
Assignee: Nigel Daley (was: Owen O'Malley)
> JobConf needs better javadoc
> ----------------------------
>
> Key: HADOOP-742
> URL: https://issues.apache.org/jira/browse/HADOOP-742
> Project: Hadoop
> Issue Type: Bug
> Components: mapred
> Affects Versions: 0.8.0
> Reporter: Nigel Daley
> Assignee: Nigel Daley
> Priority: Minor
>
> The org.apache.hadoop.mapred.JobConf class needs better javadoc comments.
> In general terms, these guidelines should be followed:
> - http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide
> - document the unchecked exceptions that the caller might reasonably want to catch
> - use <code> font appropriately (detailed in link above)
> - document default values and appropriate configuration file properties
> - comments, tags, links, etc used consistently across API
> In particular, the javadoc for this class should at least answer these questions:
> - all constructors: what happens if the supplied class, file path, or configuration doesn't exist or is null?
> - JobConf() constructor: where are default values loaded from?
> - JobConf(Configuration) constructor: indicate that this is effectively a copy constructor
> - JobConf(String) constructor: are there any format requirements on the string? local and dfs paths allowed?
> - setter methods that take a path: what happens if the path doesn't exist?
> - getter methods returning objects: if value has not been set, is null returned or something else?
> - are JobConf objects immutable? If not, why not?
> - setNum*Tasks: is this per TaskTracker? or something else?
> - methods that take a Path: what if the path is relative?
> - setWorkingDirectory: is this deleted at the end of a job? should it be local or dfs?
> - *KeepFailedTaskFiles: if they are kept, where can they be found?
> - *KeepTaskFilesPattern: what does "the files" mean? if they are kept, where can they be found?
> - deleteLocalFiles: undoubtedly a risky operation. Need a good spec. Is it a recursive delete?
> - which configuration entries are mandatory (i.e. must be set before submitting the job)?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-742) JobConf needs better javadoc
Posted by "Owen O'Malley (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-742?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12546307 ]
Owen O'Malley commented on HADOOP-742:
--------------------------------------
Nigel,
Are you willing to close this after Arun's documentation patch?
> JobConf needs better javadoc
> ----------------------------
>
> Key: HADOOP-742
> URL: https://issues.apache.org/jira/browse/HADOOP-742
> Project: Hadoop
> Issue Type: Bug
> Components: mapred
> Affects Versions: 0.8.0
> Reporter: Nigel Daley
> Assignee: Owen O'Malley
> Priority: Minor
>
> The org.apache.hadoop.mapred.JobConf class needs better javadoc comments.
> In general terms, these guidelines should be followed:
> - http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide
> - document the unchecked exceptions that the caller might reasonably want to catch
> - use <code> font appropriately (detailed in link above)
> - document default values and appropriate configuration file properties
> - comments, tags, links, etc used consistently across API
> In particular, the javadoc for this class should at least answer these questions:
> - all constructors: what happens if the supplied class, file path, or configuration doesn't exist or is null?
> - JobConf() constructor: where are default values loaded from?
> - JobConf(Configuration) constructor: indicate that this is effectively a copy constructor
> - JobConf(String) constructor: are there any format requirements on the string? local and dfs paths allowed?
> - setter methods that take a path: what happens if the path doesn't exist?
> - getter methods returning objects: if value has not been set, is null returned or something else?
> - are JobConf objects immutable? If not, why not?
> - setNum*Tasks: is this per TaskTracker? or something else?
> - methods that take a Path: what if the path is relative?
> - setWorkingDirectory: is this deleted at the end of a job? should it be local or dfs?
> - *KeepFailedTaskFiles: if they are kept, where can they be found?
> - *KeepTaskFilesPattern: what does "the files" mean? if they are kept, where can they be found?
> - deleteLocalFiles: undoubtedly a risky operation. Need a good spec. Is it a recursive delete?
> - which configuration entries are mandatory (i.e. must be set before submitting the job)?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.