TomDoc parser for PHP files
PHP Perl
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
lib
tests
README.md
php-tomdoc

README.md

php-tomdoc

php-tomdoc is a TomDoc parser for PHP files.

TomDoc is an alternative to the kludgey horridness you see in things like phpDoc or JavaDoc; rather than writing inline documentation that's designed for computers to read, you write lovely, human-readable documentation that's as readable inline as it is when it's generated.

Here's an example:

// Public: connects to the database server with the given credentials. If
//     they're ommitted, default values will be used.
//
// $hostname - The hostname of the database server (default: 'localhost')
// $username - The username to authenticate with (default: 'root')
// $password - The password to use when authenticating (default: '')
//
// Returns a new database resource.
public function connect($hostname = '', $username = '', $password = '') {

It looks much like the sort of comment you'd write even if you weren't using a particular documentation system, and reads perfectly; it just has the added bonus of being readable by a machine, too.

How to use

To generate documentation for a specific file and write it to docs/file.html, call:

$ php-tomdoc /path/to/file.php docs/file.html

To generate documentation for all the PHP files within a directory and write it to docs/index.html, call:

$ php-tomdoc /path/to/directory docs/index.html

For now, only HTML output can be generated through the command line tool, but there's a coloured console mode that will be enabled soon!

Example output

You can see an example of php-tomdoc's HTML output here.

A screenshot of its console output can be found here.

Todos

  • Write output stream for plain-text.
  • Improve HTML rendering.
  • Allow choice of output in command line mode
  • When outputting in HTML, allow choice of single file (default) or multiple files (one per source file).
  • Table of contents for single-file HTML output.
  • Make recursive file searching optional.
  • Explore proper nesting of functions within classes -- reflection?
  • Test with regular global functions (not just class methods).