drumm and I talked a fair bit about this in Szeged, and I have a todo list gathering dust on my desk for writing up some of the specifics pertaining to this, but... api.module has several areas that need working on - the large-scale priority list was a) rewrite the parser using php's tokenizer (we have also talked about the possibility of a Reflection-based parser, which has some problems but could be stupidly easy to extend), then b) port to d6. Neil/somebody, please do correct me if this is no longer accurate. And imo, those are top priority because api.module's lack of support for classes is debilitating for D7. However, there are some really interesting possibilities for including 'static' documentation, as David has suggested below. Doxygen does make it possible, although it's quite awkward. The Panels API documentation is done with doxygen, for example, and uses some such static documentation: http://doxy.samboyer.org/panels2/panels_api_plugins.html I wrote that reference with the intention of it being reminiscent of http://api.drupal.org/api/file/developer/topics/forms_api_reference.html, except that it's generated directly from documentation files that are checked in to Panels CVS here: http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/panels/docs/sam... then generated by doxygen using the doxyfile here: http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/panels/panels2.... (the ALIASES section is the substantive, and horrifying, part) I wouldn't wish the pain of that approach on anyone else, especially because I think there are a lot of better ways to do it. In particular, we might create our own @tags extending the standard set recognized by either phpdoc or doxygen. The value of an @invokes tag will be immediately obvious to most devs, but the potential for something like, say, @glossary tags for building up a network of terms for autolinking within api docs is really interesting. There are other possible avenues for expansion too, of course, but drumm's been rightfully hesitant to throw new @tags in willy-nilly. More importantly, though, ALL such discussion is moot until the basic rewrites and porting is taken care of. cheers Sam On Thursday 06 November 2008 23:28:13 David Metzler wrote:
Funny that I was having just this discussion with my Dev team at work today. How shall we document how/why something works. I think most of the folks agreed that closer to the code is better. So comments is the best answer but it's often difficult to document how disparate modules connect in code comments.
Another resource that we have that's not used as much as it could be is the API module and it's document generation techniques. It already documents much of the bigger picture with core modules. Correct me if I'm wrong, but cannot developers maintain "extra" technical documentation in a separate document along with their modules in CVS? That might be a good thing to version control, but keep a static document, that feeds api documentation. I know this is possible with other modules such as Doxygen, but am not sure that it works in API module. (but I bet it could). This is the solution we landed on in my dev shop.
That way rational/design info could(should?) be supplied with patches. In separate documentation and it would help those who do patch review understand how/why something is supposed to work before it gets committed.
You see that's the one problem with using CVS annotate. The commiter provides that message, but the patch submitter is the one who needs to supply the documentation :). And remember our goal here is to make it easier for the review/commit phase, so adding doc work to the commiter is counter productive.
So I like using CVS for why something changed, but not how something is supposed to work. That needs to be in code comments or lean text base documentation that goes with the code.
But perhaps we near exhausting all that can be said on this issue.
On Nov 6, 2008, at 8:21 PM, Angela Byron wrote:
On 11/6/08 6:19 AM, Thomas Zahreddin wrote:
Hi Angie,
thank you for answering the first third of my mail. I think we are not on the same page:
in the last third I wrote explicit, that I know all the tools and places where to find informations - but i also mention that it is impossible to follow all relevant information.
To lower the workload for us all we need a summery on a much higher level than CVS-messages (btw how many do we count a day - my estimation is two a minute).
I answered the first third, because it seemed to me that the last two thirds were based on the presumption that the information you seek is not readily available. But CVS annotate seems to do exactly what you request and it requires no manual effort on the part of our already over-burdened maintainers to keep up to date, since it's updated automatically with every commit.
In what specific ways does CVS annotate not get you what you're asking for? That would probably help the justification for your proposal be a bit more clear.
-Angie