0

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?

Jono Tho'ra
  • 1,476
  • 3
  • 18
  • 28

2 Answers2

2

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.

Peter Foti
  • 5,526
  • 6
  • 34
  • 47
  • Thank you, It is good to know there are Automatic Solutions for Inline Documentation. However my question is Academic in Nature, so I'm actually asking specifically to learn more about Inline Code Documentation Comment Blocks and how they can be used Properly – Jono Tho'ra Feb 18 '14 at 19:50
  • Following up; I installed VVDocumenter and it's working beautifully. This is absolutely an excellent Plug-in for me to have. :) – Jono Tho'ra Feb 19 '14 at 19:23
1

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.

jervine10
  • 3,039
  • 22
  • 35
  • These examples definitely look like they should work to me. It's possible i'm checking it wrong. In Xcode, I'm testing the Documentation Comments by checking it in the Intellisense briefing. Is there a better place I can check to make sure Documentation Comments are working in Xcode? – Jono Tho'ra Feb 18 '14 at 21:02
  • Try holding down the options key, hover over the method or property, and click. You should get a dialog box appearing with the document comment if one is available. This should work for apple's methods as well. – jervine10 Feb 19 '14 at 01:42
  • The headerdoc documentation is not working on xcode 7.2 and swift. Do you guys have any idea of what is happening? – Victor Tavares Feb 03 '16 at 00:12