Writing API Documentation

Question

PHP

I am a developer of the server part of the application, the task was to write documentation.
We need documentation in general for the project, but first of all, we need API documentation for colleagues developing the client part.

I would like to have the following functions:
- Auto-generation of class diagrams from code, class tree, etc. - everything in the code in phpdoc-style
- Ability to write manuals manually
- Automatic linking between manual manuals and class diagram.
- Ability to customize your generation templates (i.e. so that external API documentation is written from php classes \ methods)

While I look at www.phpdoc.org/ + write a plugin for it, a template + some kind of wiki, but maybe there is something ready and convenient.

Share your experience in documentation and especially API documentation for your project!

Answer 1

From experience, on the other hand, all this documentation on classes is not particularly needed - if necessary, you can always look in the source code what's what, but often, for substitution in the IDE, the declaration is more than enough.
Other information is needed - dependencies of calls through parameters, use cases, as a last resort, examples. As a rule, this is a couple of pages of text, if without water, but very valuable pages.
From experience - do it in the wiki. The only thing is that *doc needs to be transferred to the wiki markup by the script, but then there are no problems with creating links and maintaining it. I didn’t see a completely finished one - one way or another, they either stupidly throw in the results of the php | javadoc output, or draw themselves

Answer 2

Tests can be used as documentation. :)

Answer 3

On our projects, API documentation for developers is generated automatically (in the case of REST, examples of calling methods via cURL, in the case of SOAP, it’s not really necessary, WSDL is enough).