Index all of contrib modules at api.drupal.org

It would be another branch, so it'd be head, 5, 4.7, contrib-head, contrib-5, etc. All that'd have to be done is to set up the script to check out the new branches and add 'em to api.module config.

Oh and then 95% of contrib would basically be unsuitable because at the moment very few people document for api.module. I do in bits and pieces, but not completely. And even then there still need to be topics.

TO do contrib right we'd need to make it easy to get right to the documentation for just one module; I'm not sure it'd be good to have api.module mixing all of contrib together. It'll be very difficult to find stuff.

So maybe what we need to do is make contrib.api.drupal.org and create some way for module owners to create the appropriate branches for their module? That way the documentation can be properly contained.

I totally agree that managing branching is hard, exponentially harder when multiplied by contrib. I'd suggest just targeting contrib HEAD in the first instance, to get this rolling.

Yes, a stand-alone subdomain would be appropriate, not mixing it with core.

I first mooted this idea to illustrate that many contrib modules are incompletely documented. My thoughts are that if a system published a modules dirty laundry, it would be a great step forward in bringing the maintainers attention to this side of their code.

For folk Like Tony who are volunteering somewhat to improve things, I'd note that

Contributed patches for doc-blocks are also welcome for submission in project issues

and can probably be folded in easily as they are simply comments which should not require testing.

A cross-reference to the brilliant (if pedantic) coder.module should also be published.

I'm aware, however that contributed patches of code-style clean-ups are much harder to review and should probably be done in the first case by the real module maintainers. Wasn't there a 'code review' script that used to log lots of complaints against the contrib codebase?

To answer a few of Merlins points, I personally think that the odds are better than 95% against WRT existing modules. My experience with picking up and looking at old projects has been good.
95% of them need tidy-up work but even then, they are mostly OK.

WRT topics, I wonder if api.module (and phpdoc) don't already support that already. Perhaps documenting the usage of the @group function at the top of modules (in the @file) block would add module-name topics to module docblocks. I've not tested, but I think that's already available.

As for management ... I don't want to think about branching, but maybe an opt-in button on the project page (like the current 'link to CVS') would be a smooth start.
If that has to migrate to the 'release' definition to really work right, OK, but not yet, Mkay? Already I have trouble keeping track of which doc version I'm looking at on api.drupal.org. (tho having the history available is enlightening)

I'll go play with api.module again... see if I can add some more guidelines

Unless I miss my guess, the two most visited documentation pages would be for Views and CCK; and for Views, without branching the documentation would be pretty bad. So I'm not sure launching without branching for contrib would be a good idea.

This is a good idea.

But, as mentioned, in contrib there are many branches.

In many cases, many of them are actively maintained.

Indexing HEAD only is problematic, since many module maintainers don't bother with HEAD until a new Drupal version is out, then they sync HEAD to the latest version they were working on, then go from there. So for the longest of time HEAD would be stale/unstable.

So, do we index DRUPAL-5--1, or DRUPAL-5--2, or --3, ...etc.?
Or do we index all of them?

If all of them, then how will the interface look like for selecting the branch?

dww's new proposal is for branches to be just DRUPAL-X--N, then M, O, P, ...etc. with the number incrementing. So, I hope there are only (say) a max of 10 branches per Drupal version.

A list box? A tree?

This requires 2 things:
- API module CVS version is currently about 90% done with a menu rewrite. That needs to finish and be running.
- The server performance and hardware situation needs to be firmed up a bit.

In parallel, I will help make API module good for indexing plenty of modules. This is good for everyone, not just Drupal.org, since Drupal shops tend to accumulate modules and can maintain an internal documentation server. Please send your submissions in over at the API module project page.

The core 5.x patch queue is down to 42 patches needing review today, so I will focus a bit more time on API module.

I've also thought about this some time ago, but after looking at the code of API module I came to the conclusion that API module needs to be refactored to support zillion projects, branches and versions like in contributions. Otherwise, you won't be able to administer the API documentation.

Another thought regarding this was to develop an integration between API and Project module. Module maintainers should be able to control which branches and versions should be indexed. None by default. And there may be branches or versions that should not be published anywhere. Since each project defines its own branches and versions, API needs to query this information from project module anyway to provide a custom menu for each project. Following this, an integrated API documentation, available on f.e. http://drupal.org/project/admin_menu/api, should be the goal.

Until we get our act together, Ax's doxygen powered docs are up again for Contrib. Lots of juicy info there: http://drupal.kollm.org/doxygen/_contrib/drupal-contrib-phpdoc/modules.h...

I removed the big blockers:
* No more use of the preg_*() 'e' modifier. I didn't find any specific exploits, but decided that removal of all generated executed code is best.
* The menu rewrite is working well. There are some rough edges as noted in the API module issue queue.

Still need to figure out:
* What sort of hardware resources would this take?
* Add a concept of 'projects' to the API module, possibly integrate directly with project and/or CVS modules. I don't think parsing everything at once with the existing API module would be good for the UI.

I think this would be a very helpful feature, although I don't think that contributed modules should go into api.drupal.org. Mixing cleanly documented core API with ugly contributed API documentation is a bad idea... Maybe a contrib.drupal.org or something?

I think contrib.drupal.org would be a better name indeed.

+1 for contrib.drupal.org in #9.

I think it's easiest to let the user search for a module first (Views, for instance) and that at the next page the interface is the same as at api.drupal.org, including how all branches are shown. Perhaps it's best not to show certain older branches; hide branches 5.x-1.0 till 5.x-1.3 by default if 5.x-1.4 is the latest release. Hiding development branches might not be such a good idea, because it allows for a nice and quick peek for developers. Now I'm writing this I come to think showing branches the same way as at api.drupal.org may take up too much space. A vertical list in a block would offer a better overview.

I think only branches should be indexed as there are millions of different tags that could be available. Here are the branches that I think should be indexed:

HEAD

DRUPAL-5
DRUPAL-5--2
DRUPAL-5--3
DRUPAL-5--4
DRUPAL-5--5
DRUPAL-5--6
DRUPAL-5--7
DRUPAL-5--8
DRUPAL-5--9

DRUPAL-6--1
DRUPAL-6--2
DRUPAL-6--3
DRUPAL-6--4
DRUPAL-6--5
DRUPAL-6--6
DRUPAL-6--7
DRUPAL-6--8
DRUPAL-6--9

Although only few modules actually make it to a version 4 branch, it would certainly cover all traditional Drupal version naming....

The update status XML tells us exactly what to tags index for each project and how to label them.