How do you document your PHP functions and classes

问题:

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? 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."

回答1:

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.

回答2:

Choose from:

• Doxygen
• phpDocumentator
• Sami
• ApiGen
• CakePHP API docs
• phpDox

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

回答3:

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.

回答4:

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

回答5:

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.

回答6:

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