I am working on a project at a company that has a policy of only documenting things that are not obvious. For instance instead of:
/**
* This methods adds a document to the array of documents and optionally
* downloads the documents contents.
* @param doc document to be added
* @param download whether or not to automatically download the documents
* contents
*/
- (void)addDocumentToArray:(Document *)doc download:(BOOL)download;
only the last download parameter which is not obvious would be documented:
/**
* @param download This parameter controls whether the document's contents
* are automatically downloaded.
*/
- (void)addDocumentToArray:(Document *)doc download:(BOOL)download;
Unfortunately in the absence of a description instead of leaving it blank, appledoc pulls in the description of the first @directive it finds. In the above example it would yield "This parameter controls whether the document's contents are automatically downloaded." as the method's description, which is undesirable. Other than that it behaves as expected, displaying documentation only for those parameters with explicit documentation.
I am working on a project at a company that has a policy of only documenting things that are not obvious. For instance instead of:
only the last
downloadparameter which is not obvious would be documented:Unfortunately in the absence of a description instead of leaving it blank, appledoc pulls in the description of the first
@directiveit finds. In the above example it would yield "This parameter controls whether the document's contents are automatically downloaded." as the method's description, which is undesirable. Other than that it behaves as expected, displaying documentation only for those parameters with explicit documentation.