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