The Gist

We wanted an API documentation generator that could handle the features of Hack that aren't in PHP — async, generics, etc. So we wrote one.

Usage

A typical use case:

hphpdoc -x exclude-dir -x another-exclude-dir -o dir-to-export dir-to-parse

Doc Comments

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

However, 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;
}