Re: The Documentation!

[Chris B. Vetter]

On 1/23/07, Matt Rice <ratmice@yahoo.com> wrote:
> --- Stefan Bidigaray <stefanbidi@gmail.com> wrote:
[...]
> > like this:
> > /** Blah blah blah
> >  *   blah blah blah
> >  */
> Well, some editors add the * at the beginning
> automatically, I don't think there'd be any problem
> with you adding them.
> though those same editors generally create
> /*
>  * style comments
>  */
> if you're trying to easily differentiate the /*
> comments from /** ones

I may be wrong, but...

autogsdoc uses the /** as an indicator.

Comments that start with /** are considered relevant for class
documentation, while comments starting with a /* are considered to be
just simple comments.

Since you can use method markups to indicate whether a method is a
designated initializer, or should always/never be overwritten, it's a
good idea to put those markups in the opening /** line, eg.

/** <init>
* Use this method to initialize the receiver.
*/
- (id) initWithFoobar: (id) aFoobar;

/** <override-subclass>
* This is an abstract method your subclass must override.
*/
- (void) foobar;

Since you're going to comment all classes within the header files
(which I personally wouldn't, to keep them short), all comments should
probably start with a /** while you'd use /* in the accompanying class
files.

But I guess you already know all that...

--
Chris