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

soundasleep / phpdoc2

Maintainers

Details