Re: RE: [PEAR-DOC] Re: [PEAR-DEV] looking for volunteers phpDocumentor, new converter reST

Jon Parise wrote:

On Fri, Jun 13, 2003 at 07:36:29PM -0400, Analysis & Solutions wrote:

One of the major advantages to using a simple format like reST is the removal of the requirement that the documentation be "rendering" in order for it to be readable. In other words, it's entirely possible to author completely readable reST documents without ever rendering them using docutils.

Perhaps I'm misunderstanding the discussion. Is the thread about the format used for the documentation used in the backend of PEAR -- to generate things like the PEAR website? Or, is it about a new standard for inline docblock comments in PEAR code and packages?

It's actually about neither. I've been speaking specifically about user-level package documention, such as: http://pear.indelible.org/Net_SMTP/docs/usersguide.html

If we're talking about the latter, I think switching formats is a big mistake. A huge amount of time has gone into writing phpdoc/phpDocumentor style comments. Plus there's the massive investment in writing phpDocumentor itself -- bless you Greg, Joshua, et al!

That syntax will always be the standard method of documenting source code inline. It is most useful for generating API documentation. phpDocumentor also allows for writing user level documentation, for example, its used

to generate all the phpDocumentor docs: http://phpdoc.org/docs/HTMLSmartyConverter/HandS/ Tutorials/Manuals in the left hand nav. Now for pear of course things are a little different since we output to the peardoc2 docbook stuff instead of straight to html/pdf/etc. One possibility would be to write your user-level docs in the phpDocumentor tutorial format and then you don't have to worry about combining api/turtorial elelments (its handled automatically) plus you gain phpDocumentor's nice code highlighting, the ability to link to the apidocs in a standard way, plus the ability to grab code examples right from the original source if you want. Right now the tutorial format only supports docbook but if someone was brave reST support could be added, (actually this would be really easy with a reST to docbook converter) for more details on tutorials checkout: http://phpdoc.org/docs/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tutorials.pkg.html -joshua eichorn project admin phpDocumentor