Automatic documentation from PHP code

OK I know there's PhpDocumentor for generating documentation from php code. It seems it hasnt been updated in a long time (but maybe they figure its mostly feature complete).

While this might be good for documenting things for other programmers, it doesn't seem well suited for documenting the external "API" of a web service. IE, if I've got a nice MVC structured project, PhpDocumentor might be great for documenting all the models and internal libraries and such for other developers on that project, but how do I document the web service it provides?

I am thinking something where you could document the methods on the controllers using tags like:

/**
 @service /device/add
 @access POST
 @return JSON 
*/

which in the generated docs would show that you need to do a POST request, it returns JSON data and the URL to access it is http://whatever.com/device/add. Obviously there would be a global config file for the documentation that defines what the base url is for these service calls.

At this point I am thinking I will just implement something myself using reflection on the phpdoc blocks (or using Annotations with the addendum library) and have the docs acc开发者_JAVA技巧essible dynamically right in the application.

You might prefer DoxyGen (or PHPxRef) to PhpDocumentor .

"While this might be good for documenting things for other programmers, it doesn't seem well suited for documenting the external "API" of a web service".

Why not put DoxyGen (or whatever) comments only into the API functions which are externally visible?

Give a description of each and use @param [in], @param [out] and @return.

Wouldn't that achieve what you want? Or did I miss something?

I think what your asking (documenting an API (especially if its RESTful)) would be to use a WADL. Granted its not going to be generated from source (no tools for that in PHP), but a WADL is excellent for documenting a service.

You can have sample payloads in all sorts of media types, all the response codes and how you handle them -- really everything you need.