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

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. -- Jon Parise (jon@php.net) :: The PHP Project (http://www.php.net/)