Generate the documentation from a PHP class.
Parses a class -- must already be loaded in memory -- for all its constants, parameters and methods and documents them in a sane way.
You can get a clean HTML string or a json string.
No dependency. Less than 400 LOC.
The simplest documentation file is:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
</head>
<body>
<?php
include('ClassToBeDocumented.php');
include('Documentation.php');
$documentation = new Aoloe\Documentation('ClassToBeDocumented');
$documentation->parse();
$documentation->render();
?>
</body>
</html>That's simple:
- write the HTML "decoration",
- load the class to be documented (and the
Documentationframework"), - pass its name to the
Documentationconstructor, - parse the documentation,
- render it.
If you want to generate a static HTML documentation page simply run:
php your_documentation_file.php > your_documentation_file.html
This projects documentation is a real world example, that adds the CSS styling.
- Uses the PHP built-in reflection classes to get each
- constant,
- (public) property, and
- (public) method.
- The class and the methods can have doc comments ("JavaDoc") with:
- a freeform introductory text,
- the type of the (method) parameters (
@var,@param), - the return value of methods (
@return), - todo lists (
@todo,TODO).
- Returns
- a clean HTML text you can echon on a HTML page, or
- a json list you can further process, or
- the todo list.
- Does not differntiate between
protectedandprivate.
Basically, it adds a limited JavaDoc parsing to the PHP own reflection classes.
Doc comments can appear before:
- the class definition
- the class variables (parameters)
- the class methods
The following doc comments are recognized:
@var type [description]@parm type name [description]@return type [description]@todo description@todo- descritionTODO descriptionTODO- descrition
The default rendered returns an HTML chunk you can embed in your HTML page.
It uses the following CSS styles:
h2p.signaturep.signature span.modifierp.signature span.typep.signature span.namep.description
For a sample, check this project's documentation.
You can get the parsed array as json string.
You can also get the list of the todo items as a separate json string.
- Use it as is for small projects that you want to have documented, but where you don't want to pull in a documentation framework that is several order of magnitude bigger than your own code
- Hack it to get a documentation that perfectly matches the needs for your project.
Contribution are welcome, most of all if they lead to a reduction of the number of lines of code.
There is a todo list at the beginning of the PHP file which contains a list of features planned.
You can also add features request and issues to the GitHub issue tracker. They will be considered, as long as they fit the goals of this project.