Re: HeaderDoc misses some methods?
Re: HeaderDoc misses some methods?
- Subject: Re: HeaderDoc misses some methods?
- From: Tom Harrington <email@hidden>
- Date: Wed, 29 Oct 2003 11:25:55 -0700
On Tuesday, October 28, 2003, at 04:57 PM, Tom Harrington wrote:
I've got an Objective-C class which contains 7 method with
HeaderDoc-style comments. HeaderDoc seems to miss most of them when
generating Methods.html and CompositePage.html for the class,
producing no output for them. However, they're present in the class's
toc.html. It also produces spurious extra output for this header--
lines that have just "00" on their own. The script
(headerDoc2HTML.pl) doesn't give me anything like a warning or error.
And examining the header file doesn't seem to show any reason why some
methods would be recognized by HeaderDoc while others are not.
Has anyone else seen this, and if so, what do you do about it?
OK, I got this working, and hopefully this message will show up in the
archives the next time someone encounters the problem.
The problem is that HeaderDoc has an undocumented requirement with
regard to Objective-C methods (and possibly others, I haven't done an
extensive diagnosis). If you give the method an @abstract, you MUST
give it a @discussion too. If you do not include a @discussion, the
tool will not give you any sort of feedback that it thinks anything is
missing. But it will fail to put the method in most of the generated
files (as described above), instead just printing a "0". If you have
multiple methods without a @discussion then you may see "00", "000",
etc. I'm using HeaderDoc 7.3.0, which is the current release.
So this HeaderDoc comment on a method will be processed normally:
/*! @method doSomething:
@abstract Do something really abstract.
@discussion This method does something
@param string1 String used when doing something
@result YES if something was successfully done.
*/
- (BOOL)doSomething:(NSString *)string1;
While this method will cause HeaderDoc to fail silently:
/*! @method doSomething:
@abstract Do something really abstract.
@param string1 String used when doing something
@result YES if something was successfully done.
*/
- (BOOL)doSomething:(NSString *)string1;
I had skipped @discussion in some places because I was making a
preliminary pass through the headers, getting most of the required
stuff in place so that HeaderDoc would see the methods but leaving
detailed explanations for a separate pass. I'm now including
"@discussion Zip a dee doo dah" to keep HeaderDoc happy until I can
write these more detailed explanations.
--
Tom Harrington
email@hidden
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.