Code documentation using phpDocumentor
Posted: Sat Jul 23, 2005 1:51 pm
So I'm just getting started with phpDocumentor; some of its limitations are slightly annoying. I was wondering what people have found as decent solutions:
Problems:
1. They use @package and @subpackage tags to help organize files/classes into namespces/etc. Only the two levels of hierarchy are provided. It looks like standard practice is to put everything into one top level package.... This then leave only a very flat/broad topography for other aspects. I've been looking at using multiple top-level packages (Command_Line_Scripts,Web_Pages,Infrastructure) and then some below, or using the logical modules that the code is already subdivided into as packagess. Both are OK. I'ld still like a third level at least though.
2. Outside packages. I use the simpletest framework for writing test cases. Thus all my test case classes exten the simpletest classes. If I don't include the simpletest code tree in my "directories to document" list it throughs up lots of warnings and such. I can include the directory in the list, but then you end up with a "Simpletest" top level package that might look like its actually part of my project. If I had fewer top level pacakges, then its less of a problem and easier to make it clear that only "CompInaBox" is the project, other top levels are only included third-party modules, etc.
Anyone have any experience with solving these issues?
Problems:
1. They use @package and @subpackage tags to help organize files/classes into namespces/etc. Only the two levels of hierarchy are provided. It looks like standard practice is to put everything into one top level package.... This then leave only a very flat/broad topography for other aspects. I've been looking at using multiple top-level packages (Command_Line_Scripts,Web_Pages,Infrastructure) and then some below, or using the logical modules that the code is already subdivided into as packagess. Both are OK. I'ld still like a third level at least though.
2. Outside packages. I use the simpletest framework for writing test cases. Thus all my test case classes exten the simpletest classes. If I don't include the simpletest code tree in my "directories to document" list it throughs up lots of warnings and such. I can include the directory in the list, but then you end up with a "Simpletest" top level package that might look like its actually part of my project. If I had fewer top level pacakges, then its less of a problem and easier to make it clear that only "CompInaBox" is the project, other top levels are only included third-party modules, etc.
Anyone have any experience with solving these issues?