README

soundasleep/phpdoc2 is another PHP documentation generator, but tries to be cleaner and smarter and more extensible than existing solutions.

For example, mark up your classes and methods with PHPDoc comment blocks:

namespace Openclerk\Currencies;

/**
 * A "currency" represents some unit of measurement that can
 * be converted into another "currency" unit, e.g. through an {@link Exchange}.
 * Can also cover commodities.
 *
 * This is the base interface; other interfaces will provide additional
 * functionality as necessary.
 */
interface Currency {

  /**
   * Get the unique three-letter currency code for this currency,
   * e.g. 'btc' or 'usd'. Must be lowercase. This is not visible to users.
   */
  public function getCode();

  /**
   * @return true if this can be considered a "cryptocurrency", e.g. "btc"
   */
  public function isCryptocurrency();

  // ...
}

Using

php -f phpdoc2.php -- --directory "src/" --output "docs/"

For easy documentation generation, you can use Grunt with the grunt-phpdoc2 task. For example, see the example Gruntfile provided in the phpdoc2-openclerk.

Templates

To override or extend these templates, add --templates "dir". The generator will add this directory of templates to override the default ones. Uses openclerk/pages, which means you can call subtemplates.

Demos

• Openclerk - source
• phpunit - source

Top-level tags supported

• @throws (Class) (description)
• @param $name (description)
• @return description
• @see (Class) (description)
• @deprecated (description)

Inline tags supported

• {@link http://foo.com}
• {@link Class}, {@link #method}, {@link Class#method}, {@link Class description}, {@link Plural}s` etc
• {@code ...}

TODO

• Look at compatibility with phpdoc PSR standard and reference PSR examples
• Method and class summaries should only display the first sentance of the 'title' doc
• Highlight abstract classes
• Display inherited abstract methods on abstract classes
• @author tag
• @since tag
• @var tag
• @inheritDoc inline tag - might be tricky
• Class variables
• Class constants
• Global functions support
• Global constants
• Option for issue #123 to link to an external issue tracker
• Link through to open source projects for composer projects
• Link through to source code for GitHub projects

See also

• phpDox
• phpDocumentor
• PHPDoc