On Thu, Nov 21, 2024 at 08:13:49AM +0900, Junio C Hamano wrote: > Patrick Steinhardt <ps@xxxxxx> writes: > > > Double asterisks are typically used in contexts where comments should be > > extracted via tools like Doxygen. We don't do that in Git, so I don't > > see a reason to have the double asterisk. Our CodingGuidelines don't > > mention double asterisks, either. > > Should we add an explicit mention that we frown upon double-asterisks, > even though many have already slipped into our codebase already? A bit of history: I'm not sure if "slipped in" is accurate here. IIRC, when I proposed moving the contents of Documentation/technical/api-* into header files, there was some push-back that people preferred to be able to extract them to read as stand-alone, even if we did not support a full tool like doxygen. But AFAIK nobody ever wrote that tool (or at least if they did they did not share it with the list). So I started with "/**" as a mechanism to allow extraction, but it has probably bit-rotted Looking back in the archive, though, I think "people" was Jonathan Nieder and "push-back" is probably over-stating his position. This is the closest thread I found: https://lore.kernel.org/git/20141209222337.GA16345@xxxxxxxxxx/ I dunno what any of that means for now, though. I am OK officially declaring the "/**" thing something we we do not care about, if nobody is using them. I've added Jonathan to the cc in case he has comments. > I personally do not particularly mind people _preparing_ for that > someday when somebody starts extracting document snippets out with > these double-asterisks as clues, but unless/until we decide to (or > not to) enable doxygen processing on our codebase, let's not insist > on adding/deleting double-asterisks in new code during the review, > and let's not churn existing code with a patch that only adds more > double-asterisks or removes existing ones. Like you, I would be happy not to see patches adding or removing them in existing code. To me the point of an official declaration is just to tell people not to do so. :) -Peff
