45

For ActionScript 2, I've used NaturalDocs. However it has pretty poor support for PHP. I've looked so far at doxygen and phpDocumentor, but their output is pretty ugly in my opinion. Does anyone have any experience with automatic documentation generation for PHP? I'd prefer to be able to use javadoc-style tags, they are short to write and easy to remember.

albert
  • 8,285
  • 3
  • 19
  • 32
davr
  • 18,877
  • 17
  • 76
  • 99

9 Answers9

23

ApiGen

http://apigen.org/

ApiGen has support for PHP 5.3 namespaces, packages, linking between documentation, cross referencing to PHP standard classes and general documentation, creation of highlighted source code and experimental support for PHP 5.4 traits.

DocBlox

http://www.docblox-project.org/

PHP 5.3 compatible API Documentation generator aimed at projects of all sizes and Continuous Integration.

able to fully parse and transform Zend Framework 2

M A Hossain Tonu
  • 1,437
  • 15
  • 14
  • 1
    I would like to mention that DocBlox is the same as phpDocumenter in the below answer. Out of 3, this is the only one that didn't mixup namespaces, but maybe I'm just not getting something and having a late night brain fart. ;) – iautomation Dec 12 '15 at 09:02
  • ApiGen is a no-no if you're using some stuff from php 5.6 or 7. They're about to release 4.2 so I hope they solve the issues... because I like their layout. – Sebas Oct 07 '16 at 13:35
  • I never use docblox before but I tried apigen and phpdocumentor, apigen is the only one (that I had ever tried) that is able to generate document without expose the source code and its generated document is very very easy to understand. – vee Jan 04 '17 at 08:00
19

There are two well-known and often-used tool that can generate API doc from docblocks :

  • phpDocumentor, which is specific to PHP, and is probably one of the most used tool for PHP projects
  • and Doxygen, which is more for C, but is used for PHP by some people.


About the "guidelines" : I would say it depends on your projects, but, at least, I would expect to see :

  • a description of what the method/function does
  • parameters, with @param type name description of the parameter
  • return value, with @return type description of the return value
  • exceptions, with @throws type description of the exception that can be thrown

A great thing being that recent IDE (like Eclipse PDT, for instance), can read and interpret those markers, to provide hints when you're coding ;-)


Also, there are more and more PHP tools that use php docblocks for some other purpose than documentation.

For instance, PHPUnit allows you to specify some test-related stuff using some specific tags -- see Annotations.

albert
  • 8,285
  • 3
  • 19
  • 32
Pascal MARTIN
  • 395,085
  • 80
  • 655
  • 663
  • Thank you for the very thorough answer. In particular, this matches what I'm used to writing for JavaScript (dynamically typed vars and params), so given I'm not so constrained, I'll go with something that is what I'm used to. – jeremyosborne Dec 18 '09 at 05:58
6

PHPDoc is probably as good as you'll get it in terms of Javadoc style inline commenting. You might also want to look at PHPXRef.

Kornel Kisielewicz
  • 55,802
  • 15
  • 111
  • 149
6

Yes, phpDocumentor (http://www.phpdoc.org/) is an acceptable standard tool for PHP autodocs. It's the de-facto standard.

It's acceptable to follow the general JavaDoc guidelines for code when documenting PHP code. However, you're going to run into cases where that's not enough because PHP and Java are different languages.

For example, PHP functions have no return type and it's inevitable (and sometimes desirable) for a function to return one type with one context, and another type with in a second context. JavaDoc guidelines aren't going to help with that, because it's impossible to do in Java.

Alana Storm
  • 164,128
  • 91
  • 395
  • 599
  • 1
    Thanks for the reinforcement of that. I sometimes expect PHP to be a little less like a scripting language, but the more I use it, it seems like the server side scripting component of the JavaScript I usually write. – jeremyosborne Dec 18 '09 at 06:00
  • While your example is valid, generally speaking, if java does not allow something and php does, I would try to match what java recommends and not do it in php even though I could... – Sebas Oct 07 '16 at 13:28
4

phpDocumentor can output in a style similar to the php.net documentation (and its built in with both smarty and non smarty layouts)

Ólafur Waage
  • 68,817
  • 22
  • 142
  • 198
  • It's a great option but keep in mind that files containing traits or php7's return or argument type declaration are skipped by the current version (2.9.0). – halfpastfour.am Sep 28 '16 at 21:41
4

Check out PHPDoctor http://peej.github.com/phpdoctor/, a simple yet full features Javadoc clone for PHP.

Paul James
  • 41
  • 2
3

The Wordpress code-base is documented using phpdoc tags (see this) and it's generally pretty good - it's rendered here using phpDocumentor.

Most of the code that I write that's substantial enough that I need to think about autogenerating docs for is done in .Net, so I can't give much of a documentation writer's perspective though

cori
  • 8,666
  • 7
  • 45
  • 81
1

If ugly's a problem, I'd just switch the stylesheet for a custom one. If you don't want to overwrite the generated one, you can use a Firefox plugin like Stylish.

Aupajo
  • 5,885
  • 6
  • 30
  • 28
0

You could edit the template file to add your own stylesheet to override the existing one.

Darryl Hein
  • 142,451
  • 95
  • 218
  • 261