How do you document your PHP functions and classes inline? [closed]

Posted on

How do you document your PHP functions and classes inline? [closed] – Here in this article, we will share some of the most common and frequently asked about PHP problem in programming with detailed answers and code samples. There’s nothing quite so frustrating as being faced with PHP errors and being unable to figure out what is preventing your website from functioning as it should like php and documentation . If you have an existing PHP-based website or application that is experiencing performance issues, let’s get thinking about How do you document your PHP functions and classes inline? [closed].

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.”

Solution :

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.

Choose from:

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

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.

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

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

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.

Leave a Reply

Your email address will not be published. Required fields are marked *