Re: Doxygen

>>> Not that we have the energy to do something new, but I like the sound
>>>  of Doxygen - http://en.wikipedia.org/wiki/Doxygen
>>>
>>> It looks to be compatible with PHPDoc with some nice additions and
>>> might be more powerful.  I especially like the idea that you can
>>> document function parameters in a way that makes them more likely to
>>> be documented, updated, etc., which is a constant problem in SM.
>>>
>>> Anyone used it before?
>>
>> I've seen it around, but I haven't tried it myself. I don't mind if we
>> change, but I won't mind if we don't either.
>
> I think the nice thing is that it appears to be compatible with
> PHPDoc, so technically, it's just a matter of which tool you use to
> create your docs.  However, if we start using the alternate parameter
> documentation syntax, we'd be committing to Doxygen.

Nothing that a bit of scripting can't fix.

>> A quick look at the Wikipedia
>> page didn't give me any clues about why Doxygen would be better for
>> documenting "function parameters in a way that makes them more likely
>> to be documented, updated, etc." Could you please elaborate on that?
>
> Instead of:
>
> /**
>  * Add a variable to the session.
>  * @param mixed $var the variable to register
>  * @param string $name the name to refer to this variable
>  * @return void
>  */
> function sqsession_register ($var, $name) {
>
> You'd have the param docs more in the code - more in your face:
>
> /**
>  * Add a variable to the session.
>  * @return void
>  */
> function sqsession_register ($var, ///< mixed $var the variable to
> register $name) { ///< string $name the name to refer to this variable
>
> Definitely a bit more ugly, but it does look like it makes it harder
> to miss updating the docs.

Ugly indeed. Can't say I'm too keen on it, but feel free to vote me down.

Sincerely,
Fredrik

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
-----
squirrelmail-devel mailing list
Posting guidelines: http://squirrelmail.org/postingguidelines
List address: [email protected]
List archives: http://news.gmane.org/gmane.mail.squirrelmail.devel
List info (subscribe/unsubscribe/change options): https://lists.sourceforge.net/lists/listinfo/squirrelmail-devel