I’m working in a php project that needs to generate 3 or more documentations, ones more restrictive than others.
For documentation, I use PhpDocumentor 2.
The only way I’ve found is for 2 level of documentation, using @internal tag and –parseprivate option (for generate a private documentation).
Is posible to generate a third documentation with an intermediate restriction level?
I’ve also tried @access tag with –visibility, but it doesn’t work in version 2 of phpDocumentor.
Or @ignore tag, but I didn’t found a way to generate a third documentation with code setted with this tag.
Advertisement
Answer
The @access tag is a defunct PHP4 tag, to use before actual visibility keywords were added to PHP5. PhpDocumentor 1.x would recognize the tags, but if the keywords were in the code, the tags would be ignored. 2.x doesn’t even bother with those tags anymore.
“Intermediate level” is a rather arbitrary description. All three “levels” here would need some particular requirements spelled out, and would likely be best managed by three different phpdoc.xml configuration files.
Here’s an example of how I might describe three levels of docs, and how I’d accomplish them.
API-level: I’d use a file-based argument to only document the interfaces. If the @api tag is used in the docblocks to denote the actual individual pieces of the public API, then you could just rely on those. However, I think the presentation of this info in the documentation is actually just a highlighting sidebar, whereas my approach of specifically documenting the interfaces means the whole document is solely the defined interfaces (which I presume to be “the API”).
App-level: I’d capture all classes, but go with the default behavior of only showing public visibility components.
Dev-level: I’d use the –parseprivate to show all components. I also do tend to put developer-targeted information into @internal tags myself.
Again, I’d use customized phpdoc.xml config files for each of these, so that my definitions could be committed to version control.