How do you document your PHP functions and classes inline?

Question

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

What do you mean by your latest edit? I don't get what you mean by "how to generate this inline documentation". — Thomas Owens, Jul 25 '09 at 19:14
Sorry, to clarify: I'm asking how to generate the type of code commenting (or "inline documentation") in the example. — James Skidmore, Jul 25 '09 at 19:16

score 48 · Accepted Answer · edited Mar 25 '19 at 16:09

48

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.

edited Mar 25 '19 at 16:09

albert

8,285
3
19
32

answered Jul 25 '09 at 19:08

zombat

92,731
24
156
164

3

PHPDocumentor is probably the most common and the recommended way to add API documentation. – Jani Hartikainen Jul 25 '09 at 19:10
Is it possible to generate inline documentation with PHPDoc though? I thought that was only for generating documentation manuals. – James Skidmore Jul 25 '09 at 19:11
+1 Works really well and integrates with netbeans. – Mark Davidson Jul 25 '09 at 19:15
4

I wanted to make a distinction: PHPDoc is a syntax for comments (adapted from JavaDoc) http://en.wikipedia.org/wiki/PHPDoc. PHPDocumentor is *one* of the tools that can read these comments and produce usable documentation pages/XML. There is also Doxygen, and probably others. – grantwparks Jul 25 '09 at 19:56
@grantwparks - That's a good clarification to make, thanks. My link went to PHPDocumentor as I use that as a reference for PHPDoc syntax, but I generally use Doxygen for generation. I'll adjust the link to go to the syntax reference instead. – zombat Jul 25 '09 at 20:05
In vim, you can use [snipMate](http://www.vim.org/scripts/script.php?script_id=2540) to create function and classes along with documentation. – cnvzmxcvmcx Jan 13 '15 at 01:41

score 8 · Answer 2 · edited Jan 13 '19 at 14:29

8

Choose from:

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

edited Jan 13 '19 at 14:29

albert

8,285
3
19
32

answered Jun 26 '15 at 15:55

Benoit Blanchon

13,364
4
73
81

score 1 · Answer 3 · answered Jul 25 '09 at 22:16

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.

Olaf Erlandsen · Answer 4 · 2018-12-14T15:29:20.410

1

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

edited Dec 14 '18 at 15:29

answered Feb 16 '14 at 21:08

Olaf Erlandsen

5,817
9
41
73

Spelling of @ sinse should be @since :') – Ravinder Payal May 15 '16 at 13:11

score 0 · Answer 5 · edited Mar 26 '19 at 11:37

0

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.

edited Mar 26 '19 at 11:37

albert

8,285
3
19
32

answered Jul 25 '09 at 19:08

Thomas Owens

114,398
98
311
431

score 0 · Answer 6 · answered Jul 26 '09 at 04:18

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

How do you document your PHP functions and classes inline?

6 Answers6

Linked