Re: collision beam with staff-crossing beam

[address@hidden]

On 13 févr. 2013, at 13:50, David Kastrup <address@hidden> wrote:

>> I would rather make a concerted effort where people decide on a style
>> for documenting our API (standardizing function names, documentation
>> style, etc.) and then we do it rather than doing a piecemeal job.
> 
> Mike, you can either increase the ratio of undocumented functions and
> APIs whenever you add new ones, or you can decrease it.  The latter is
> not all too hard, so it makes sense to go for it.

The most time I lost in LilyPond development in my first couple years was from 
reading comments that for some reason were obsolete or non-indicative of what 
was actually going on.  Once I started just reading the logic of the code, 
everything got much easier.  So I am 100% pro telling the story but this needs 
to be done in a coherent way.  I realize that talking about user documentation 
is a different issue, but I think it needs to benefit from the same coherence 
and uniformity.

> 
>> Someone needs to lead this.
> 
> That's just an excuse for not documenting anything.  I don't buy your
> premise that things need to get worse until some hero appears and
> actively makes them better.

This is not an excuse for not documenting anything.  Every time I add a 
property I document it because there is a structure in place w/ ample examples 
of how to do so.  Ditto for interfaces.  Ditto for LY_DEFINE.

An API for LilyPond is a long talked about, excellent idea.  Once someone who 
is passionate about it comes up with rules about how it is done, like C++ 
indentation, I will follow it to the best of my abilities, exactly as I do for 
properties and interfaces and LY_DEFINE.

> 
>> Graham did this sort of thing for documentation a few years back and
>> it was an excellent idea.  The discussion could be organized in the
>> same way as GOP and GLISS stuff.
> 
> It is not a matter of "discussion".  It is a manner of making it a
> principle to write down what one was thinking instead of just coding the
> outcome, whenever it is relevant to understanding code.

This is where I get the most help from reviews - I add comments when people ask 
me what things do.  It is not obvious to me when things are relevant and not.

Cheers,
MS