Just quickly on committing api.module documentation along with patches - I started an issue here to have the hook_* documentation committed to core: <a href="http://drupal.org/node/314870">http://drupal.org/node/314870</a> - which I think goes at least some way towards what you're describing.<br>
<br>Nat<br><br><div class="gmail_quote">On Fri, Nov 7, 2008 at 5:28 AM, David Metzler wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
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.<br>
<br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br></blockquote></div><br>