Re: Re: Auto-generated API documentation

> > I'm not sure sure about this. Examples are a valuable resource when > > figuring out how a package (without documentation in the manual probably) > > works. Having the source code of the examples readily available in the API > > documentation might be handy then. But if you are interested in examples, you will open and read the relevant files. You will not browse the API, first because most PEAR examples do not define classes and packages (they are just procedural lines of code), and second, because this is of no use. I suggest that you have a look at the auto-doc of PHP_UML, and tell me you find it clear and useful, in terms of documentation... Who cares that, under /examples, there are packages called "Orion", or "Cassiopeia" ? It's just disturbing, to say the least. Note that I am not discussing the utility of examples (otherwise, I would not include some in PHP_UML). But there are other means to include sample code in an API. In the new release of PHP_UML that I am actually preparing, I have added tags <code>...</code> inside the class comments. This is, IMO, much more suitable for documentation purpose, than including classes and packages that have nothing to do with the API, and which, in worst cases, will mess it up. Baptiste