We were lacking documentation while we develop themes or plugins for the Opencart but found PHPDoc which makes our documenting our PHP projects easily. A good programmer who takes responsibility for communicating with other programmers must support documentation. Whenever we write code we started thinking of 5Ws and write each for better documentation
5Ws for better documentation
What, when, where, how, and why should be answered while creating better documentation. We came up with the following ideas to list in our documentation. It is just our idea, yours can be totally different.
What: Power Statement
“What” will be a title, which includes Issues Titles, Steps title, new Features Title, functionality title, etc
When and Where: Description
“When and Where” will be included in the description. The description will include:
- An excerpt that you can write
- Tools/Websites/Template name/Plugin name
- Include Ticket links
- Github code links
Why: Codes and logic implemented
In the “Why” section we add codes and logic
How: Output Test/Reports/Metrics
In the “How” section we add output, test, reports, and metrics.
Example of the PHP project documentation
<?php /** * This is a file Summary. * * This is a file description * @package File * @filesource */ namespace { /** * This is the summary of a constant in the global namespace. * * To check if the description is displayed correctly we *check* if it is handled correctly. And * if it shows any [Markdown](http://daringfireball.net) formatting. */ const GLOBAL_CONSTANT_DEFINE_WITH_ROOT_NAMESPACE = 'test'; } namespace My\Space { define('GLOBAL_CONSTANT_DEFINE', 'test'); /** * @package Constant */ define('Namespaced\\GLOBAL_CONSTANT_DEFINE', 'test'); /** * @package Constant\Specific */ const GLOBAL_CONSTANT_CONST = 'test'; /** * @param integer $param1 Example of a description & with ampersand (&). * @param string $param3 */ function globalFunction($param1, \stdClass $param2, $param3 = '') { } /** * A reference implementation for a subclass. * * This subclass's package has a different case than the superclass to test issue #558. * * @package class */ class SubClass extends SuperClass { /** * @var integer The first property in a list * @var \stdClass $propertyListItem2 The second property in a list */ public $propertyListItem1; public $propertyListItem2; }
You can use multiple tags listed below which you can use in the comments Docblock:
https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/index.html
Once you added the comments like above then you can generate the docs by PHPdocs.
Download phpDocumentor.phar
Download https://phpdoc.org/phpDocumentor.phar and move it into your project folder. Then we ran
php phpDocumentor.phar -d ./ -t ./docs
After we ran this, we got the docs folder in the project folder.
After this go to the docs folder where you see multiple folders like below then open index.html
When you open index.html in the browser you will see something like the below:
With these simple steps and adding comments in the code we are in the process of becoming good developers, you guys also can start making the documentation so easy for developers. Hope you will start documenting your project easily, let us know if you have any questions or suggestions, please subscribe to our YouTube Channel for Opencart video tutorials. You can also find us on Twitter and Facebook. Enjoy!
Rupak,
I would argue generating static documentation is very old school, like mainframe old school 1950’s think.
We now have everything we need to generate documentation on demand via PHP reflection classes.
I also find the quality of the generated documentation is not up to the latest responsive mobile friendly standards. Plus it takes time to generate the documentation, and we tend not to do it, and even if we do regenerate it, it does not reflect the changes to the code we just added, since we did not regenerate it since the last time we saved our changes.
So I solved all these problems with PHPFUI/InstaDoc. Install it via Packagist and add it to your project in about 2 minutes. Complete, always up to date and hyperlinked documentation!