On 13 févr. 2013, at 13:50, David Kastrup <d...@gnu.org> 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 _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
