One thing I find conspicuously missing from drupal.org is API documentation for contributed projects. We've put a lot of effort into coding and documentation standards, and this is paying off in improving Drupal core. But we are not seeing any benefit of this in the contrib space. Contrib modules really have no incentive to provide extensive Doxygen documentation because no-one ever sees it.
Where do I go to see API documentation for View, Rules, CTools, Ubercart, and other large contributed projects? We should make a home for these on api.drupal.org. Even small contributed projects should be able to host their API pages on api.drupal.org. Initially, this can be done through an opt-in process like the one that was/is currently in use for automated testing on drupal.org (where projects can opt-in to have SimpleTests run for every patch posted in their issue queue). This has been a tremendous help for very active projects. Automated generation of API documentation and automatic hosting on api.drupal.org could also be a major improvement.
Comments
Agree
I agree. Right now, API documentation for most(?) contrib modules can be found at http://drupalcontrib.org/api/drupal. But it makes sense to host that on drupal.org.
I think there might be security issues with it, though – pulling doxygen from files and outputting on web pages could (I guess) potentially result in bad things. While core is well monitored, it would probably require some secure filtering and things before all contrib code could be allowed to be both processed and displayed.
But yeah, it definitely makes sense to have that on drupal.org. (Come to think of it, this discussion must have occured several times in the past…)
//Johan Falk
//Johan Falk
**
Check out NodeOne's Drupal Learning Library! 200+ screencasts and exercises, for Drupal introduction, advanced configuration, and coding. Creative Commons license!
API docs suggestions/actions
Summary of our experience with doing doc for a contrib module (Dick Johnson's Bulkpub module, which is still in the sandbox stage):
- Comments in the code (which can be picked up and turned into doc using Doxygen) appears to be required and enforced by the module reviewing team.
- However, the doc that COULD be automatically created apparently is not required (at least not by default).
- Every project needs to have a project page.
- However, although there is a "tips for a good project page" doc out there, a template and approved examples would be even more helpful.
Suggestions:
- We agree with TR's suggestions that API doc be posted on api.drupal.org. Since there is apparently already a requirement to put in the comments that could result in automated doc, why not require the developer to publish and post it?
- Instead of the tips for a good project page, why not get agreement on the required and optional sections and enforce the requirement as projects move from sandbox to full-blown project? Is there a mechanism for doing this?
Suggested API doc strategy:
- There seem to be 2 audience types: users and developers
- There seem to be 4 doc "types": (1) project page (both audience types), (2) technical overview (both audience types), (3) interface reference material (both audience types, for example, web service calls), and (4) API reference material (only for developers, this is the automated doc mentioned above).
- We think it would be good to at least encourage contrib module developers to include all 4, if relevant.
- We think 3-6 examples would be useful to developers.
- We would be willing to participate in creating an "approved" example, if the group decides to proceed on this.
Actions:
- We did an earlier doc prototype for Dick's Bulkpub, and with additional information and thoughts we're going to revise it to be: (A) A Bulkpub user guide, handcrafted, that contains doc types 1-3, created in DITA/XML and published as a Drupal 7 book using Dick's Bulkpub module, and (B) an API reference created automatically using Doxygen.
- We'll post all this temporarily for review on our drupalinfo.info site. If it seems useful in any way to the API effort we'd be glad to morph it into a template of set of examples, or whatever.
-Anna and Dick
In the plans...
Contributed modules are supposed to follow the coding standards for Drupal as a whole, including the documentation standards at
http://drupal.org/node/1354
Drumm has plans to put all of contrib onto api.drupal.org. However, we may need to work out a few issues in the API module around having all those different projects included, such as what to do about searching, and how to handle cross-project links. You can check the API project issue queue and help out.
http://drupal.org/project/issues/api
And just as a note, api.drupal.org is only for developer reference documentation (functions, classes, etc.). Any module developer can create pages on the drupal.org documentation for user-docs, tutorials, etc.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon