Re: Re: Auto-generated API documentation

On Tue, Jun 10, 2008 at 6:42 AM, Brett Bieber <brett.bieber@gmail.com> wrote: > On Tue, Jun 10, 2008 at 3:06 AM, Martin Jansen <martin@divbyzero.net> > wrote: > > Baptiste Autin wrote: > >>> > >>> --ignore */data/*,*/tests/* > >> > >> Thanks a lot Martin. > >> > >> Wouldn't that make sense to exclude /examples/* too? > > > > 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. > > I agree - examples should be included in the auto-generated > documentation.. and I would hesitate to remove any documentation that > may be there already. > > But I can see the need for a developer to omit specific files within > the API docs. I'm not sure if this is possible, but I recall some > discussion in IRC about a feature for phpDocumentor which would omit > the entire file @ignorefile. Anyone know the status of this? Chuck? > My inclination would be towards using the @example tags [1] in order to pull in the content from example files, to appear as documented info in the API docs in a structured way. Blindly including all content from an examples/ subdirectory will lead to mixed results, IMO... at best, the example files would be docblock'd well enough that useful info would appear in the generated docs (though this might have been better visible in the class/method it's demonstrating), but I'd bet most of the time these files would generate no useful docs aside from appearing on the Files listing (i.e. leaving you only the option of reading the raw source of the files). -- CRB [1] http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.example.pkg.html