The org.apache.hadoop.mapred.JobConf class needs better javadoc comments.
In general terms, these guidelines should be followed:
- 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)?