Login | Register
My pages Projects Community openCollabNet

Discussions > dev > Re: [propel-dev] phpdoc tips?

propel
Discussion topic

Hide all messages in topic

All messages in topic

Re: [propel-dev] phpdoc tips?

Reply

Author hlellelid
Full name Hans Lellelid
Date 2004-06-03 17:56:09 PDT
Message That's awesome, micha!

Perhaps you should send your diff back to doxygen team also, although I
suppose it would affect parsing for other langauges?

Anyway, I will try to install this tonight (have been busy); if I can't
do it tonight, I'll do it over the weekend & build the docs. Let's plan
to use Doxygen as official Creole / Propel doc generation system.
Thanks again for your help on this. Looks great!

Hans

Michael Aichler wrote:

>Hi,
>
>Well, one hour was a bit too short ;)
>I've noticed that the member attributes do not have a type in the
>documentation and tried to fix this as well - but gave up for now...
>
>Anyway, the @param tag accepts now "<type> <name>" and "<type>.<name>".
>
>Cheers,
>micha
>
>


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

[propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-03 17:44:00 PDT
Message Hi,

Well, one hour was a bit too short ;)
I've noticed that the member attributes do not have a type in the
documentation and tried to fix this as well - but gave up for now...

Anyway, the @param tag accepts now "<type> <name>" and "<type>.<name>".

Cheers,
micha
--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc
Attachments

Re: [propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-03 13:14:22 PDT
Message Hi Hans,

On Thursday 03 June 2004 21:53, Hans Lellelid wrote:
> > 1) I'll change the patch tonight to get it recognize a space instead of a
> > dot
> > (or both).
>
> That would be ideal, if possible.

Ok, I'm working on it. I'll try to finish it by next hour and post it so that
you can test it when you're at home.

Btw, are there any other things that could/should be improved/changed ?

> > Also, does this mean that we cannot use the @ingroup tag to group things
> > together ?
>
> No, no. I just mean that we should try to preserve the syntax for those
> tags that are recognized (like @param). That's all. If we changed to
> using type.$varname then I don't think the other parsers would even be
> able to recognize the $varname part -- much less the type. That's why I
> was saying that in that case we'd be breaking compatibility; I think being
> compatible is worth something. That doesn't preclude using new tags that
> the other parsers don't support -- that's fine.

Ah, well then.
The @param tag shouldn't be a problem - till one hour ;)

> We may have to decide
> whether we want to *also* use @package tags, but I'm not so worried about
> that. (I have to think about what the packages should be for Propel,
> which isn't as straightforward as Creole -- and I don't think it
> necessarily makes sense to just use java-style directory-based package
> naming).
>
> Cool work!

Thx!

> Hans
micha

--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc

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

Re: [propel-dev] phpdoc tips?

Reply

Author hlellelid
Full name Hans Lellelid
Date 2004-06-03 12:53:56 PDT
Message Hi,

> As for the types; I do not want to miss this feature now that it is
> available ;)
> Here are some suggestion how to remain compatible:
>
> 1) I'll change the patch tonight to get it recognize a space instead of a
> dot
> (or both).

That would be ideal, if possible.

> Anyway, if we want to have compatibility with other documentation tools
> then
> we'll miss a bunch of useful tags provided by doxygen (see
> http://www.stack.nl/​~dimitri/doxygen/com​mands.html#cmdvar )
> Also, does this mean that we cannot use the @ingroup tag to group things
> together ?

No, no. I just mean that we should try to preserve the syntax for those
tags that are recognized (like @param). That's all. If we changed to
using type.$varname then I don't think the other parsers would even be
able to recognize the $varname part -- much less the type. That's why I
was saying that in that case we'd be breaking compatibility; I think being
compatible is worth something. That doesn't preclude using new tags that
the other parsers don't support -- that's fine. We may have to decide
whether we want to *also* use @package tags, but I'm not so worried about
that. (I have to think about what the packages should be for Propel,
which isn't as straightforward as Creole -- and I don't think it
necessarily makes sense to just use java-style directory-based package
naming).

Cool work!

Hans

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

Re: [propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-03 10:52:30 PDT
Message On Thursday 03 June 2004 18:46, Hans Lellelid wrote: > First: that's cool; aweome work :) Heh, I wanted to have this feature for php but didn't have the motivation to look into doxygens source code ;) > 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? Yes, the varname is taken from the function definition. As for the types; I do not want to miss this feature now that it is available ;) Here are some suggestion how to remain compatible: 1) I'll change the patch tonight to get it recognize a space instead of a dot (or both). 2) We provide a simple php script that converts the @param tag back, e.g: ----- $file = file_get_contents("./Creole.php"); $file = preg_replace('/\@param\s+(\w+)\.(\$[a-zA-Z_][a-zA-Z0-9_]*)/', '@param \1 \2', $file); echo $file; ----- 3) Doxygen nows about a tag called @fn (aliases are @var and @typedef) that initiates a function declaration, e.g.: @fn Connection getConnection(string $phptype, string $dotpath) It would be possible to search this tag in a comment block and extract the return value and param type information. Anyway, if we want to have compatibility with other documentation tools then we'll miss a bunch of useful tags provided by doxygen (see http://www.stack.nl/~dimitri/doxygen/commands.html#cmdvar ) Also, does this mean that we cannot use the @ingroup tag to group things together ? micha -- MediaCluster GmbH Webentwicklung Michael Aichler Alt-Wuerttemberg-Allee 42 71638 Ludwigsburg Tel.: +49 71 41 - 90 64 42 Fax.: +49 71 41 - 90 64 43 Email: aichler (at) mediacluster (dot) de PGP: https://www.mediacluster.de/pgp/aichler.asc --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@propel.tigris.org For additional commands, e-mail: dev-help@propel.tigris.org

Re: [propel-dev] phpdoc tips?

Reply

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

[propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-03 07:23:02 PDT
Message Hi,

> > The docs you created look great, though. Perhaps a little less info than
> > some of the phpdoc stuff (var type for params seemed missing),

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 ?

I updated the online documentation, however only the creole class is
completely updated to the new tags:

http://www.aichler.n​et/creole/5/docs/htm​l/classCreole.html

The attached patch contains both qt-style and php support.
You need to patch a vanilla doxygen source tree as this patch conflicts with
the two from yesterday, sorry.

Cheers
micha

--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc
Attachments

Re: [propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-02 05:59:16 PDT
Message On Wednesday 02 June 2004 14:45, Hans Lellelid wrote:
> Hi micha,
>
> This looks great; thanks for taking the time to do that. I'm going to
> review the tags- files to see what needs to change & take a look at
> applying the patch -- and see just what is involved in customizing the
> parsing & output -- on my linux box at home tonight.

Ok, great ;)

> The docs you created look great, though. Perhaps a little less info than
> some of the phpdoc stuff (var type for params seemed missing),

The var type is missing as the @param tag of doxygen takes only the name of
the var. The type is guessed by doxygen which failes for php (except for
typehints).

> but far
> more intuitive & usable. Is the introduction text (on landing page)
> extracted from a phpdoc-style comment somewhere or is that a separate
> file?

Both ;)
Doxygen has LateX-style tags to create pages, sections, etc.
See mainpage.dox in the tarball.

>
> Also, I can get a smaller version of the logo for the header.

Yeah, definitely needed ;)

micha

--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc

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

Re: [propel-dev] phpdoc tips?

Reply

Author hlellelid
Full name Hans Lellelid
Date 2004-06-02 05:45:41 PDT
Message Hi micha,

This looks great; thanks for taking the time to do that. I'm going to
review the tags- files to see what needs to change & take a look at
applying the patch -- and see just what is involved in customizing the
parsing & output -- on my linux box at home tonight.

The docs you created look great, though. Perhaps a little less info than
some of the phpdoc stuff (var type for params seemed missing), but far
more intuitive & usable. Is the introduction text (on landing page)
extracted from a phpdoc-style comment somewhere or is that a separate
file?

Also, I can get a smaller version of the logo for the header.

Cool! Thanks!

Hans



> Hi Hans,
>
> I made some changes to the doxygen scanner last night and it seems to work
> now
> - at least better ;)
> I attached the php5 patch for doxygen version 1.3.7 (the latest) and the
> qt-style patch.
> Apply the patches inside the doxygen directory with
>
> patch -p1 < /path/to/doxygen-1.3​.7-php5.patch
> patch -p1 < /path/to/doxygen-1.3​.7-qt-style.patch
>
> I changed a few comments in the php5 source and generated the
> documentation
> with doxygen. A tarball including header, footer, css and Doxyfile files
> can
> be downloaded at
>
> http://www.aichler.n​et/creole/5/creole-p​hp5-doc.tar.gz
>
> Online documentation:
>
> http://www.aichler.n​et/creole/5/docs/htm​l/index.html
>
> However, we have to change some documentation tags.
> All attached files named tag-* describe the most important changes that
> have
> to be done.
>
> Hopefully this is enough information to decide whether it 's worth
> switching
> to doxygen - if not, let me know ;)
>
> micha
> --
> MediaCluster GmbH
> Webentwicklung
>
> Michael Aichler
> Alt-Wuerttemberg-Allee 42
> 71638 Ludwigsburg
>
> Tel.: +49 71 41 - 90 64 42
> Fax.: +49 71 41 - 90 64 43
> Email: aichler (at) mediacluster (dot) de
> PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc
> --------------------​--------------------​--------------------​---------
> To unsubscribe, e-mail: dev-unsubscribe@prop​el.tigris.org
> For additional commands, e-mail: dev-help at propel dot tigris dot org


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

Re: [propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-02 05:30:57 PDT
Message Hi Hans,

I made some changes to the doxygen scanner last night and it seems to work now
- at least better ;)
I attached the php5 patch for doxygen version 1.3.7 (the latest) and the
qt-style patch.
Apply the patches inside the doxygen directory with

patch -p1 < /path/to/doxygen-1.3​.7-php5.patch
patch -p1 < /path/to/doxygen-1.3​.7-qt-style.patch

I changed a few comments in the php5 source and generated the documentation
with doxygen. A tarball including header, footer, css and Doxyfile files can
be downloaded at

http://www.aichler.n​et/creole/5/creole-p​hp5-doc.tar.gz

Online documentation:

http://www.aichler.n​et/creole/5/docs/htm​l/index.html

However, we have to change some documentation tags.
All attached files named tag-* describe the most important changes that have
to be done.

Hopefully this is enough information to decide whether it 's worth switching
to doxygen - if not, let me know ;)

micha
--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc
Attachments

Re: [propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-01 12:58:26 PDT
Message On Tuesday 01 June 2004 21:03, Hans Lellelid wrote:
> Hi micha,
>
> Yes, I agree. I was able to get PhpDocumentor to output PHPEdit-styled
> docs using the following command:
>
> phpdoc -d classes -t docs\api -dn "Propel" -ti "Propel API Docs" -o
> HTML:frames:phpedit
>
> but I'm still very unhappy with these docs; they're still basically
> useless.

Yes, unfortunately ;(

> > A preview of creole's php4 api is at
> > http://www.aichler.n​et/creole/docs/api/h​tml/index.html .
>
> This looks much better -- I like that all the classes can be browsed in
> addition to the modules. Very clean. I might make some trivial changes
> to the method detail list to make it clearer where one method starts &
> ends, but that's just stylistic & I imagine that can be changed.

Yeah, should be possible with css.


> I like the way that it cross-references text from within the docblocks
> (like constants, methods) -- did you have to add code to make that happen
> or is that automatic?

This is mostly done automatic and a great feature of doxygen (see
http://www.stack.nl/​~dimitri/doxygen/aut​olink.html ).

> I've heard good things about doxygen, just never used it.

Heh, I was "forced" to use doxygen as kdevelop dropped support for kdoc ;)

> What kind of changes would we need to make to the sourcecode / phpdoc to
> use doxygen?

For example the @package tag is interpreted by doxygen as a "namespace".
I created the modules list with @defgroup and @ingroup (there might be a
better way - I'm not completely familiar with all tags of doxygen)
 
> Is it reasonable to think that I could sit down w/ doxygen
> for a couple evenings & get PHP5 support working? (i.e. do you know how
> difficult it would be to modify the PHP4 parser?)

Well, doxygen uses lex (or yacc) for parsing the files. The modifications I've
done applied only to a few html tags in htmlgen.h/htmlgen.cpp. I had no
closer look at the parser itself, so I cannot say something about it yet.
However, I'll find out how difficult it would be.

Another possibility would be to write a script (perl, php, whatever) that
reads all php5 files, preprocesses the code to something doxygen is able to
parse and writes the code to a single file which is processed by doxygen
afterwards !??

>
> > How do you think about it ?
>
> Cool, am interested :)
>
> Hans

micha

--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc

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

Re: [propel-dev] phpdoc tips?

Reply

Author hlellelid
Full name Hans Lellelid
Date 2004-06-01 12:03:43 PDT
Message Hi micha,

> I do not have any tips on phpdoc or another php tool for api documentation
> as
> I wasn't able to configure anyone of them to output clean and functional
> documentation (from my point of view ;)

Yes, I agree. I was able to get PhpDocumentor to output PHPEdit-styled
docs using the following command:

phpdoc -d classes -t docs\api -dn "Propel" -ti "Propel API Docs" -o
HTML:frames:phpedit

but I'm still very unhappy with these docs; they're still basically useless.

>
> IMHO the best documentation style I've ever seen is from QT's Toolkit
> (http://doc.trolltech​.com/3.3/index.html)​.
>
> Doxygen is the only tool I found whose output is close to QT's
> ( unfortunatly doxygen's php5 support is quite limited - more precisely
> unusable at the moment).
>
> I patched the source a little so that it's *more* close ;)
> A preview of creole's php4 api is at
> http://www.aichler.n​et/creole/docs/api/h​tml/index.html .
> I'd like to use it for the php4 version. There have to be changed a few
> tags,
> though.

This looks much better -- I like that all the classes can be browsed in
addition to the modules. Very clean. I might make some trivial changes
to the method detail list to make it clearer where one method starts &
ends, but that's just stylistic & I imagine that can be changed.

I like the way that it cross-references text from within the docblocks
(like constants, methods) -- did you have to add code to make that happen
or is that automatic?

I've heard good things about doxygen, just never used it.

What kind of changes would we need to make to the sourcecode / phpdoc to
use doxygen? Is it reasonable to think that I could sit down w/ doxygen
for a couple evenings & get PHP5 support working? (i.e. do you know how
difficult it would be to modify the PHP4 parser?)

> How do you think about it ?

Cool, am interested :)

Hans


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

Re: [propel-dev] phpdoc tips?

Reply

Author Michael Aichler <aichler at mediacluster dot de>
Full name Michael Aichler <aichler at mediacluster dot de>
Date 2004-06-01 11:30:27 PDT
Message Hi Hans,

I do not have any tips on phpdoc or another php tool for api documentation as
I wasn't able to configure anyone of them to output clean and functional
documentation (from my point of view ;)
However, your mail reminded me of a question I wanted to ask you some days
ago.

IMHO the best documentation style I've ever seen is from QT's Toolkit
(http://doc.trolltech​.com/3.3/index.html)​.

Doxygen is the only tool I found whose output is close to QT's
( unfortunatly doxygen's php5 support is quite limited - more precisely
unusable at the moment).

I patched the source a little so that it's *more* close ;)
A preview of creole's php4 api is at
http://www.aichler.n​et/creole/docs/api/h​tml/index.html .
I'd like to use it for the php4 version. There have to be changed a few tags,
though.

How do you think about it ?

micha

--
MediaCluster GmbH
Webentwicklung
  
Michael Aichler
Alt-Wuerttemberg-Allee 42
71638 Ludwigsburg
  
Tel.: +49 71 41 - 90 64 42
Fax.: +49 71 41 - 90 64 43
Email: aichler (at) mediacluster (dot) de
PGP: https://www.mediaclu​ster.de/pgp/aichler.​asc

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

[propel-dev] phpdoc tips?

Reply

Author hlellelid
Full name Hans Lellelid
Date 2004-05-31 21:38:52 PDT
Message I'm trying to generate some API docs for Propel. I'm using PHPDoc
1.3.0RC3, I believe -- whatever the latest version is (the one that
finally works w/ PHP5). I'm able to generate the docs, but they just
look crappy. I'm used to docs built by PHPEdit's plugin (just much
cleaner, but also more functional), and I know that I've seen some
people use a PHPEdit template for PHPDoc too.

Does anyone have INI files (or configuration tips) for PhpDocumentor
that make decent & usable API docs?

I've got Propel broken into Java-style packages right now, but it would
be nice to be able to see all classes, or browse by files too. I don't
know if these features are just missing or what. Every time I go to the
PhpDocumentor site to get help, I get completely frustrated with their
"manual". The online docs at that site are just completely unusable --
mostly due to the fact that they're written using phpdoc, which I
strongly believe is a case of "just because you want to prove you can
doesn't mean you should." This idea that PEAR loves of writing
tutorials from within the API docs is just ludicrous ... ok, </rant>. :)

Once I get this working, it'll be great, I'm sure. Now that
PhpDocumentor supports PHP5 I'd like to create a <phpdoc/> Phing task &
a target in build-propel.xml so that API docs can be built as part of
the om generation.

Anyway, thanks in advance for any tips, etc.

Hans

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