PHP project documentation

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
Documentation Terminal Command

After we ran this, we got the docs folder in the project folder.

Documentation folder Opencart developer

After this go to the docs folder where you see multiple folders like below then open index.html

Docs files and folder

When you open index.html in the browser you will see something like the below:

Developer Documentation Opencart project

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!

LEAVE A REPLY

Please enter your comment!
Please enter your name here