appertly/hphpdoc

An API documentation generator for Hack/HHVM and PHP

0.4.0 2016-10-03 15:40 UTC

Requires

• hhvm: ~3.12
• appertly/axe: ~0.1
• appertly/axe-markdown: ~0.1
• appertly/cleopatra: ~0.1
• fredemmott/definition-finder: ^1.3.3
• psr/log: ^1.0.0

Requires (Dev)

• hackpack/hackunit: ~0.6
• libreworks/psr3-log-hhi: ^1.0.0

Apache-2.0

• documentation
• php
• api
• hack
• hhvm

README

API Documentation Generator for Hack/HHVM and PHP

Check out some example documentation: actually, it's our own API. Please have a look.

Installation

You can install this library using Composer:

$ composer require appertly/hphpdoc

• The master branch (version 0.x) of this project requires HHVM 3.12 and depends on appertly/axe, appertly/cleopatra, and fredemmott/definition-finder.

Compliance

Releases of this library will conform to Semantic Versioning.

Our code is intended to comply with PSR-1, PSR-2, and PSR-4. If you find any issues related to standards compliance, please send a pull request!

Usage

You can view a list of all command line options with the -h or --help flags, or by simply calling the hphpdoc executable with no arguments.

Usage:  hphpdoc [options] [--] [args...]

hphpdoc generates API documentation for Hack and PHP files.

Options:
  -h --help     Show this help screen
  --version     Displays version information
  -v --verbose  Increases verbosity level (can be used more than once, e.g.
                -vvv)
  -q --quiet    Prevents any output except errors; supercedes the verbose
                setting
  -x --exclude  Excludes specific files and folders from scanning (can be used
                more than once), wildcards are not supported
  -o --output   Specifies the directory for generated documentation; defaults
                to PWD

For example:

hphpdoc -v -x tests -o build/api .

PHPDoc Syntax

For the most part, we're trying to cover everything in PSR-5. This initial release covers many tags, but not all of them just yet.

Being that Hack has more strict typehints than PHP 5, you can omit types from your @var, @param, and @return PHPDoc tags if you choose!

/**
 * @var You can omit the type here, or…
 */
protected string $something = "nothing";
/**
 * …you can just specify a description here. The type is detected automatically!
 */
protected Vector<string> $test = Vector{'foo'};
/**
 * This is my method.
 *
 * This is a description.
 *
 * @param $name - The name
 * @param $numbers - The numbers
 * @param $log - The log
 * @return - The thing you need. Always specify a dash before description.
 * @throws \RuntimeException if anything goes wrong
 */
public function getFoo(string $name, ConstVector<int> $numbers, Psr\Log\LoggerInterface $log): ?Foo<Bar>
{
    return null;
}

If your return type or parameter typehint is mixed, hphpdoc will fall back to the PHPDoc tag type, if one is specified. Example:

/**
 * @return array<string>|string|null The return type
 */
function nope(): mixed
{
    return null;
}