Roadmap

I can work from time to time on phpSimpleDoc, and plan to spend time on it on fall 2008 ; I'll try to have a stable version in winter 2009.
Before I stop working on it for a couple of month, here is a list of unfinished points.
See also file todo.txt

For version 1.0

Debug, document correctly, test, better the design of generated pages.
In particular : try to find exhaustive syntax for declaration of different code elements (is there a PHP language specification somewhere ?)

Reach a stable design

See below

Documentation inheritance

Implement javadoc's algorithms which permit :
- to classes or interfaces to inherit documentation from their ancestors (at class, method and parameter levels).
- to classes to inherit documentation from the interfaces they implement.
- to use @inheritDoc tag to mix inherited comments with comments specific to the subclass.

Documentation coverage

Once the documentor has loaded the elements to document, it can compute the list of missing documentation and generate reports.
Documentation inheritance must be implemented before.

Documenting files and directories

Parallel circulation through files and dirs.

Pages for functions, constants, class constants and methods

Current pages are not adapted to procedural code with many functions and constants ; pages listing class fields

Design

The design of phpsimpledoc hasn't reached a satisfying state.
My main purpose is to have a program that one can easily extend or adapt.

Documentors

It's possible to write extensions of phpsimpledoc : write a new documentor ; extend an existing one ; modify an existing one writing new contents generators and adding config directives, then modifiy the main helpers to tell them to execute the new helpers.
Maybe gather in one place (a config file) the lists of helpers and subhelpers to render modifications easier (suppress the main helpers).

Helpers and auxiliaries

To perform its job, a documentor uses helpers and auxiliaries ; helpers perform part of the run ; auxiliaries helps the documentor to provide functionalities to its helpers.
For the moment, there are 2 root classes (Helper and Auxiliary), and that's not satisfying.

MVC

Not used in the current design, because the View part of phpsimpledoc is seen as the interaction with the user through index.php, so reduced to almost nothing.
But it can be seen differently : the View part of the program are the generated pages. Instead of being interactive views (as in an usual MVC application), they are static views.
Then documentor and helpers are the Controllers
The model corresponds to auxiliaries (permit data access) ; Model is also related to DataLoaders, used to build the data structure.

Future possibilities

Using tags to generate other pages

Use particular tags (@todo, @deprecated...) to generate pages containing the code elements marked with these tags.

Code source files

html pages containing the source code are generated (in user's command file, option active of section sourceCodePage).
Generate links from html source code pages back to the other pages of generated doc (Doxygen implements this feature).

Dependencies

The documentor provides an array of loaded classes ; it's easy to find their use in the code with patterns like : "/$className::/"or "/$className->/" So it's possible to build arrays of dependencies between classes (then between packages), and represent them graphically. This method doesn't catch all dependencies (like the use of class in a Registry)

Documenting magic methods and fields

__get() and __call() permit to define fields and methods which are currently not documented.
I haven't found a simple way to retrieve them, and maybe the only solution is to document them one by one.
For the moment, I just use the tags @magicGet and @magicSet, without exploiting them. This would permit to list the magic fields and method, but a more elaborate convention should be established to be able to generate a complete documentation (first sentence, parameters etc.).
@todo see doc of PhpDoc talking of a @magic tag.

Doc-files management

Javadoc's implementation of doc-files permits to write in the comments links to external documents.
It's possible to write a helper gathering the doc-files, and generating structured html documentation, with links from the usual generated documentation.
It's also possible to give the choice between several behaviours : for example, one helper which would take the files located in doc-files, and one helper which would take the files from external directories. That would be useful for example for this site : part of the articles dealing with phpsimpledoc could be included in the generated documentation for phpsimpledoc.
For that, it's necessary to decide of a convention.
PhpDocumentor is having a similar feature, which permits to include the user guide in the generated documentation.

Templates

Page generation could be rewritten to permit choice of output format. This is possible with Doxygen and PHPDocumentor ; maybe include a templating system.

@logo tag

To generate class diagrams for classes that produce visual stuff.

Javadoc tags in non-code files

Ability to extend doc comments to .ini, .html, .css, .xml, files, README, LICENCE etc.
So all the files accompanying a program can have a uniform presentation.

Grouping elements

I often find the need to group documented elements. For example, if I have a line inside a class : public $x1, $x2, $x3;, I'd like to write only one comment. This could be possible with a tag @group :

/** 
  Common comment for $x1, $x2 and $x3
  @group 3
*/
  public $x1, $x2, $x3;

To tell the documentor : the next 3 variables are part of the same group, so the current doc comment should be associated to these 3 variables.

Maybe an other solution could be more interesting :
Adopt a convention saying that if the first tag encountered in a doc comment is @group, then the whole doc comment is considered as a group comment, and is not associated to a particular code element.
Then in regular comments, an other tag (for example @belongsTo) would indicate that the corresponding element belongs to a group.
It would then be possible to generate documentation for groups.
This could be useful for classes with a lot of elements, to present related elements together.
For example, in class Zend_Form_Element of the Zend framework, there could be a group for elements related to decorators, one for validators etc.