Login | Register
My pages Projects Community openCollabNet

propel
Reply to message

* = Required fields
* Subject
* Body
Attachments
Send reply to
Topic
Author (directly in email)
Please type the letters in the image above.

Original message

Author hlellelid
Full name Hans Lellelid
Date 2004-06-03 09:46:06 PDT
Message Hi,


> I managed to get the parameter types into the doxygen documentation.
> It's quite a bad hack - however it works, so - who cares ? ;)
>
> Doxygen's param tag : @param <name> <description>
>
> For php it is now: @param <type>.<name> <description>, e.g.
>
> @param string.$phptype The phptype (mysql, mssql, etc.)
>
> The return type is fetched from the @return tag.
>
> Not too expensive, isn't it ?

First: that's cool; aweome work :) Next, not to discredit your work, but
it seems to me that it might make more sense to leave the types out or
make an effort to specify them in the description. w/o this patch it
still will get the correct varname even when type specified, right?

The reason for this is that ideally our documentation should be as widely
compatible (phpdoc) as possible; the convention used for PHP is to specify
the type before varname and there are several parsers that understand this
(PhpDocumentor, PHPEdit, I think even origi PHPDoc). If we introduce a
new syntax, then our code won't be usable with these other systems.
Without the syntax, doxygen is still gonna give us great docs. And if
people want to use another doc system they can. Also, I believe that some
advanced editor features like PHPEdit's code hints use phpdoc to provide
the hints/help, so we should aim to keep our phpdoc as standard as
possible IMO.

Does that make sense?

Hans



--------------------​--------------------​--------------------​---------
To unsubscribe, e-mail: dev-unsubscribe@prop​el.tigris.org
For additional commands, e-mail: dev-help at propel dot tigris dot org