[MAPREDUCE-412] JobConf needs better javadoc - ASF JIRA

XML

Word

Printable

JSON

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)?

relates to

HADOOP-2046 Documentation: improve mapred javadocs