Re: [SM-DEVEL] Doxygen

[Paul L. <pa...@sq...>]

On Wed, Jun 11, 2008 at 4:48 AM, Fredrik Jervfors
<jer...@sq...> wrote:
>> 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.

> 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.