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
