ansaurus

Question

Answer 1

A:

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.

Mr-sk 2010-01-22 02:06:47

That WADL stuff is interesting. I will look more into that. I'd like to see something that does WADL does using DocBlock comments in PHP, and a parser that produces documentation from those (and maybe WADL files too).

Greywire 2010-01-23 02:56:24

I'm not sure WADL is the right thing here. WADL seems to be more about defining the web service in a way that can be used to generate code, rather than the other way around (code with comments that can generate documentation).I think what would be really cool is some kind of completely generic generator that lets you define whatever tags you want and provide handlers for those. This would play well with concepts like Annotations where you are making up your own types of tags (ie, the annotation means something to the code as well as to the documentation generator)

Greywire 2010-01-23 19:43:19

Answer 2

+1 A:

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?

Mawg 2010-01-22 02:36:50

Because I also want to document the internal stuff for other programmers (not to mention myself)...

Greywire 2010-01-23 19:16:11

yes, I understood that. But if you add comments *only* for the interaces, and then run DoxyGen, then you have generated interface docs which you can give to others.Wouldn't taht work?

Mawg 2010-01-24 02:58:16

I'm not sure what you mean by comments only for the interfaces?If you mean, document the controller methods as the external service calls, and the models as internal, that wont work in my design because there is a generic controller for standard CRUD operations on any model, so the only place to document is in the model method (I am also using annotations to define the db access for the model, etc).

Greywire 2010-01-25 21:11:23

Now that I've sat down to work on this, I tried just using the @param tags to document the POST variables that a method accepts through the web interface. Problem here is that phpDocumentor assumes these are arguments to that method, and so thats what the docs show, which is wrong. I was also thinking I could use @link to show what the actual URL would look like, but its kinda confusing in the generated docs.

Greywire 2010-02-03 22:08:26

ansaurus

tags:

views:

answers:

Automatic documentation from PHP code.

related questions