[development] Reviewing patches and making decisions -> Sociocracy could be a way to go!

[Sam Boyer]

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/sample_plugin_ct.inc?revision=1.1.2.3&view=markup&pathrev=DRUPAL-5--2

then generated by doxygen using the doxyfile here: 
http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/panels/panels2.doxy?revision=1.1.2.8&view=markup&pathrev=DRUPAL-5--2
(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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
Url : http://lists.drupal.org/pipermail/development/attachments/20081110/a856598e/attachment-0001.pgp