Question

Problem:
There Should be a Documentation Comment written for each Method in the example SCParserDelegate Protocol.


Context:
I'm Building a Parsing Framework to be used by 3rd Party Developers. (This is my first Framework project, so my development process is Highly Academic to maximize learning.)


Sample Code:

/** @protocol SCParserDelegate
 *   @brief Protocol for a Delegate to handle Callbacks when an SCParser finds Tags
 */
@protocol SCParserDelegate
@required
@property (readonly) BOOL processing;
@optional
-(void)parserDidStart:(SCParser *)parser;
-(void)parserDidFinish:(SCParser *)parser;
-(void)parser:(SCParser *)parser didOpenTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser didCloseTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser didSingleTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser whitelistDeniedTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser parseErrorOccurred:(NSError *)parseError;
-(void)parser:(SCParser *)parser foundCharacters:(NSString *)content;
@end


Question:
How can I Manually Write my own Documentation Comment Blocks for each Method and Property within the Sample Code above?

Was it helpful?

Solution 2

NSHipster has good comments on this. http://nshipster.com/documentation/

As for delegates its good to inform whoever is conforming to the protocol of when the messages will be sent, so for example:

/*!
 * @field processing   Flag indicating that the operation is currently in process
 */
@property (readonly) BOOL processing;

/*!
 * Sent right after the parser began
 * 
 * @param parser (Something about the parser)
 */
-(void)parserDidStart:(SCParser *)parser;

/*!
 * Sent after the parser opens the given tag (maybe some hints as to what the delegate may do)
 *
 * @param parser (Words about the parser)
 * @param tag    (Something about the tag)
 */
-(void)parser:(SCParser *)parser didOpenTag:(SCTag *)tag;

There's other tags which are helpful such as @return and @warning. VVDocumenter is quite helpful so I would recommend installing that.

OTHER TIPS

It sounds like you want to use something like VVDocumenter.

From their Github page:

Writing document is so important for developing, but it is really painful with Xcode. Think about how much time you are wasting in pressing '*' or '/', and typing the parameters again and again. Now, you can find the method (or any code) you want to document to, and type in ///, the document will be generated for you and all params and return will be extracted into a Javadoc style, which is compatible with appledoc, Doxygen and HeaderDoc. You can just fill the inline placeholder tokens to finish your document.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top