On Fri, Dec 12, 2014 at 10:31 AM, Jonathan Nieder <jrnieder@xxxxxxxxx> wrote: > Jeff King wrote: > >> I'm not sure any such thought as "intended to be out of date" went into >> it. > > Junio started the documentation in v1.5.4-rc1~49 (2007-11-24). I'm > not sure if there was a discussion preceding that commit. My > understanding was always that putting the documentation out-of-line > was an intentional decision and that it was understood that the > documentation would have cycles of falling out of date and needing to > be updated, but I may be misunderstanding the history. > > Separate from the question of history, I honestly prefer this way of > doing API documentation relative to 90% of the API documentation in > headers I've seen in other projects. I suspect you don't. That's > okay --- it's possible for rational people to disagree about things. > > It's moot given that we don't seem to disagree about what should be > done about it. Why keep arguing? > So you proposed an order of desirability w.r.t. the way we want to go documenting things. > Some possibilities, in order of my preference (earlier items are better): > > 1. Move documentation to header and provide a program to generate a nice > standalone document. Junio agrees with that order. Michael said > My vote is for putting the API docs in the header files: which seems to be an agreement with your most desired way to do it. Jeff said earlier when reviewing your patch: > I somewhat feel this goes in the opposite direction of where we want to > be *(all data in one place, but that place is the header)*. which sounds to me as if he prefers also the header as the one place of truth. I do agree on your proposed order of desirability as well. So nobody showed up yet, who dislikes the headers as the one place of truth. So the open question is: * The historic reasoning to introduce technical/api-$header at all. As Junio mainly put persons to ask into the stubs in 530e741c726 (2007-11-24, Start preparing the API documents.), it was probably improving the status quo back then. Maybe it was easier to have all names in place than using git blame/git pickaxe at the time? Answering this question makes sure we don't oversee some reasons. * Assuming we put everything into headers now, we'd need to discuss -> Do we want to extract it to technical/api-$somedoc later at all? (There seems to be some disagreement?) -> How do we extract (plain sed for lines starting with "*", or doxygen, or a self cooked script) -> How do we ensure the generated documentation doesn't get stale over time? As I personally just look up things in the header anyway, I'd rather get started on polishing the comments in the headers as on arguing how to extract it. Though that's a required step to know which format we want in the headers. Thanks, Stefan -- 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