Jeff King wrote: >> Jeff King wrote: > We could probably do a better job of keeping our header files neat and > well-ordered. And perhaps would so if they had a coherent narrative in > the first place. The example I was looking at before was refs.h. It is still a mess. Hopefully strbuf.h will work better. [...] > On Tue, Dec 09, 2014 at 02:23:37PM -0800, Jonathan Nieder wrote: >> I suspect a simple tool to extract the comments and produce something >> like the technical/api-* files would help, since then when someone >> writes a patch, they could try the tool and see if the result is still >> easy to read. > > That seems like wishful thinking to me. Some subset of developers will > be happy reading the documentation in the header file, and will not > commonly run the tool. Therefore they will also not bother to examine > the output of the tool when making a change (either because they forget, > or because it is simply a hassle that they do not care about). That is okay as long as enough people extract documentation to ensure the result is sane. It is similar to what happens with Documentation/*.txt. A subset of developers just work with the source and make local changes without looking at the big picture (and sometimes buggy markup or documentation organized in a confusing way results). But that doesn't change much. When people forget to look at the manpage and write text that is awkward in context or markup errors, one of a few things happens: * a reviewer notices. The patch is fixed, and the patch author develops better habits for next time. * someone using the documentation notices later, and it gets fixed then, which is still fine. Both outcomes are much, much better than documentation that never gets organized. [...] > The api-* files have slowly grown out of > date over the years, and I believe that is because they are too far > removed from the code people are actually touching. I don't think they ever were very comprehensive or up to date. As far as I understand, the api-* files are intended to be usually out of date. Their main purpose is to explain the gist of how to use the API. They were usually written way after the API was introduced (so they are behind already). They are clearly written and as long as they mostly match the code, that is enough for them to be useful and educational. Then every few years or so, someone updates the file with the latest API changes, still with an eye to overall organization and readability of the document. In other words, they prioritize clarity over currency. Of course if it's possible to have clear documentation that also matches the current code, that would be even better. I have hope that moving the documentation to the header files will get us there if we do it right. > I did drop some asciidoc-specific formatting from the main text (e.g., > "+" lines for connecting blocks), which means that extracting the result > and running it through asciidoc won't work. This unfortunately lost some structure (e.g., which paragraphs were part of the same bulleted list). It would be more common to use a hanging indent: - The `buf` member is never NULL, so ... string operations ... by `strbuf_init()` ... Do not assume anything about what `buf` really is ... ... - ... [...] > I think it makes the actual > text much more readable, though. But we could do it the other way if > people really want to asciidoc it. I also don't mind losing the asciidoc markup, especially given that it would be a pain to reconstruct and render. My reaction at first glance is that this is trying to do something good but the current implementation is less readable than Documentation/technical/api-strbuf.txt. Am I looking at a work in progress, or is this meant to be ready for application? Which aspects would you be interested in comments on? Thanks, Jonathan -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html