appertly / hphpdoc
An API documentation generator for Hack/HHVM and PHP
Installs: 41
Dependents: 1
Suggesters: 0
Security: 0
Stars: 3
Watchers: 2
Forks: 2
Open Issues: 1
Language:Hack
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
This package is not auto-updated.
Last update: 2024-11-04 07:05:51 UTC
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
, andfredemmott/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; }