Stefan Beller <sbeller@xxxxxxxxxx> writes: >> I agree on both counts. I just like to read these in plain text >> while I am coding for Git (or reviewing patches coded for Git). >> >> The reason why I have mild preference to D/technical/ over in-header >> doc is only because I find even these asterisks at the left-side-end >> distracting; it is not that materials in D/technical could be passed >> through AsciiDoc. > > /** > Would we be open to consider another commenting style? No. You still cannot write */ in that comment section, for example, so you cannot do "plain text" still---that is not a great trade off to deviate from the common comment style used for other stuff. When I say I want plain text, I mean it. Anything you write in .h cannot be plain text, unless you make all readers agree with some convention, and "there is always '*' at the left edge" is such an acceptable convention can learn to live with, just like everybody else does ; at least, that is consistent with other comments. > (I am not seriously proposing unbalanced comments, but for > longer documenting comments we may want to consider, > omitting the asterisk?) If this is not a serious proposal, then I'll stop wasting everybody's time. Now it is clear that the only pieces of consensus we got out of this discussion so far is that we want to add to CodingGuidelines, that my earlier "something like this" is not the text we want and that we want everything in the header as comment. So let's see if we can have usable alternative, apply that and move on.
