http://www.phparch.com \ November 2018 \ 33Producing Packages, Part Two
The Workshop
The doc blocks allow us to specify what our method is
going to do “Sum 2 numbers” as well as what types we expect
our parameters to be (floats) and we plan to return a value of
the float type. While these types will not be honored at run
time, many editors and IDEs (such as JetBrains’ PhpStorm)
will read the doc blocks and show warnings and hints based
on their value. You can read more about doc blocks and all
the different options on the phpdoc.org^5 site.
Taking our doc blocks to the next step we can install
phpDocumentor^6 and GraphViz^7 so we can run the phpdoc.
phar binary against our src folder to generate our documenta-
tion for us. Usage of phpdoc.phar is to call the phar file, supply
a source directory of code to parse, and
specify an output folder to write the
HTML docs to. We’ll run the command
like so:
php phpDocumentor.phar -d ./src -t ./docs
And get the output in Figure 2.
Now we have a docs/ folder contain-
ing the output from phpdoc.phar as
shown in Figure 3.
If we open the docs/index.html file
in a web browser we see our generated
documentation as in Figure 4.
We can click through our our Easy-
Math namespace and click on our
Addition class to see phpDocumentor’s
summary and description of our code.
See Figure 5.
5 phpdoc.org: https://docs.phpdoc.org
6 phpDocumentor:
https://phpa.me/installing-phpdoc
7 GraphViz: https://www.graphviz.org
Figure 2 Figure 3Figure 4Figure 5