The standard autodocumentation tools wouldn't help
much either.
- The bulk of the work is extracting information from
LilyPond's internals. Take predicates. Their mapping
to names is maintained in the code, so we would have
to make the tool aware of our predicates.
- Our concepts of "grobs", "interfaces", "engravers",
"contexts", etc. are not understood by tools that
work in terms of "classes", "methods", "members"
and such.
From what I understand, the core of the documented items is in the C++ code. But if you autogenerate the documentation from that code, you would have a set of classes and functions in a different "language" than
the one used in the current documentation. Then you have to extract all these infos and translate them to your conventions (grobs, interfaces, engravers etc.). This is why I suggested a "static" wrapper, which should not be difficult to maintain because, even
if introduces a redundancy with the set of names, this set will not be expanded or changed in the future. I mean: TimeSignature won't be replaced with something else in the future, and (I suppose) it's unlikely that new concepts will be added.
New grobs and engravers are often created. As LilyPond continues to evolve in the future, one should not assume that the set of elements in the Internals Reference is constant. One of the great things about the current documentation system
is that when one adds a new grob or engraver, as long as the added element functions in LilyPond, no changes *at all* are needed to the documentation infrastructure. It just works on the existing code.
Then a "TimeSignature_wrap", with links to the respective comments in the C++ code, won't be changed. So: what do you mean with "their mapping is maintained in the code"? From what I see, once the mapping is statically
done it should not be maintained. Anyway, I could be wrong and in any case I'll show you some practical examples of what I have in mind in the next days.
The thought of having to make a “TimeSignature_wrap”, as opposed to a “Grob_wrap”, is antithetical to the LilyPond core principles. We insist that, as much as possible, internals documentation be created from executable code, rather than
comments about the code, because we don’t want the documentation to diverge from the actual code. Thus, the interfaces listed as affecting BarLine don’t come from somebody keeping a list of the interfaces related to BarLine, they come from the bar_line_engraver
declaring (in the C++ code) the interfaces actually used. And there is virtually no static mapping.
Once a static mapping is done, it *must* be maintained if it is to remain accurate. It’s even worse if it seldom needs to be changed, because editors are less likely to remember things that seldom change and don’t affect the code.
While the current system may not be the prettiest possible system, or the easiest to use, it’s very hard for the documentation to actually be wrong. And I think that correctness of internals documentation is more important than ease of
use (although I would love to see our internals reference be easier to use).
I would love to see some practical examples of what you have in mind! I hope they will be sketches of what you have in mind using the LilyPond code base, rather than using some other code base. Of course, I wouldn’t expect a practical
example to be implemented on the whole LilyPond code base; I’d just love to see it on a part of the code base. Something kind of like Jean’s code that showed how it could be possible to get all the properties (and where they were defined) programmatically
for any given grob.
I love the fact that you want to improve the LilyPond documentation! I look forward to your contributions.
Thanks,
Carl