Home » Php » documentation – How do you document your PHP functions and classes inline?

documentation – How do you document your PHP functions and classes inline?

Posted by: admin April 23, 2020 Leave a comment

Questions:

I know there are many different standards for PHP code inline documentation. Here’s what I mean by inline documentation, and please correct me if there is a better term:

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/
class orderActions {
...

What is the best and most widely-accepted form of inline documentation? In other words, what are those forms of inline documentation that everyone agrees on, and are not significantly based on opinions; the universally accepted forms of PHP in-line documentation that everyone should know about, but as a questioner, I’m not sure of yet, but after this question is answered, I will have a good overview of, not involving any particular opinions.

Are there any tools to auto-generate such documentation, or does it have to be done by hand?

I’m not interested in generating manuals — I want to know how to generate the type of code commenting above, or “inline documentation.”

How to&Answers:

PHPDoc, like what you’ve posted, is a widely accepted form of PHP documentation.

You can use Doxygen to auto-generate the docs.

Edit: In terms of generating in-line documentation in your code, I have never come across a tool that will go back and do this externally for a project. It’s generally left in the realm of the IDE to generate a template while you code.

Eclipse actually does a decent job of this (it’s one of the few things I like about Eclipse) and I believe Netbeans does as well. Any major IDE will likely have functionality to assist with this type of template generation.

Answer:

Choose from:

See also the Wikipedia article, “Comparison of documentation generators”, section “by Language”.

Answer:

Usually, you would write the docblock comments your self, although I suppose some IDE’s can create a template for you.

I did actually write a program, which can trace a running program and detect parameter types and write them back as docblock comments. It’s a bit buggy, but it kind of works.

Answer:

I created a documentator which is very simple to use and compatible with phpdoc:

Example:

<?php
    $docs = new QuickDocumenter();
    $docs->parseString("
    /**
    *   Sanitize string
    *
    *   @since      1.0
    *   @version    1.0
    */
    ");
    foreach( $docs->result() as $doc)
    {
        highlight_string( print_r( $doc , true ) );
        echo "<hr/>";
    }
?>

See in Github:

https://github.com/olaferlandsen/QuickDocumenter

Answer:

Not sure what you code in but I have several snippets (I use Textmate) that I just add in as I’m working) I’ve found this ends up with the best results since I’m filling in the details instead of trusting a system to do it for me.

It’s more work in the beginning but it seems to be worth it in the long run

Answer:

Although I haven’t fully utilized it, Doxygen looks promising for this task.

If you are familiar with the JavaDoc tool for Java, it’s quite similar to that. You use the Doxygen style and then run the tool over your source files to produce documentation.