phpSimpleDoc > Roadmap

Version 1.0 alpha4

For version alpha4, a deep refactoring and code cleaning is needed.

For the moment, I develop other stuff, take holidays ; I will have time for phpsimpledoc in automn 2009

The main planned modifications are :
- Current data structure handles php code, packages, files and directories ; modify it to store data coming from different languages.
- Isolate the code dealing with the "model" ; the model deals with the documented code and the documentation process.
- Generate documentation for text files (.ini, .xml etc), at least display the source of text files.
- Permit the generation of different outputs : implement html and serialized php array.
- Permit the computation of data structures from different input ; implement source files and serialized php array.
- For PHP code : permit several ways to mark a comment ; permit several syntaxes for doc comments.
- Php code loader : mechanism of hooks to permit new functionalities without polluting the main loops.
- New user directives to take profit of the enhancements.
- Clean code to assist the documentation run : web usage interface, report, debug, performance measure.

Version 1.0

Document javascript files

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.

"Thrown by", "class use"

For an exception, give the list of functions or methods throwing it.
For a class, a method, a function, a variable, links to code using it.

Documentation coverage

Once the documentor has loaded the elements to document, it can compute the list of missing documentation and generate reports.
This functionality is implemented since version alpha1, but was not included as an available option, because without documentation inheritance, it leads to wrong results (the documentor says "this element hasn't been documented" if it doesn't find documentation for it, but does not see if a parent element contains a comment).

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.

Code source files

html pages containing the source code are generated (in user's directive 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).

Minor functionalities

• Permit to specify several files / directories as input ; adapt package definition for this case.
• Implement common documentor features (link to custom api etc., cf javadoc, phpdoc).

Future possibilities

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->/" or "/extends $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.).

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 could have a uniform presentation.