In C/C++, I would often use documentation-after-member (as supported by Doxygen) because it makes better use of available screen space (and thus improves comprehension by reducing load on the reader’s working memory).
As an example, consider this example usage from a hypothetical symbolic math library:
/// Kind of operation performed by a binary expression.
enum BinaryOperation {
SUM, ///< addition
PRODUCT, ///< multiplication
POWER, ///< exponentiation
LOG ///< logarithm
};
and compare it to what we’re required to do now:
/// Kind of operation performed by a binary expression.
enum BinaryOperation {
/// sum
SUM,
/// multiplication
PRODUCT,
/// exponentiation
POWER,
///logarithm
LOG
};
I regard these “oh noes think of the noobs!”-type arguments as circumspect — it’s like saying we should ban all non-round doorknobs so people don’t get confused. Comments are a stylistic choice; the bikeshedding should focus on the cost/benefit of supporting the features under discussion.
Benefit: better ergonomics of doc-comments for those who wish to make use of this style
Cost: code to support the style will need to be maintained.
So then, here’s what I’m asking:
What I Want to Know: Is there sufficient interest in this or a similar syntax for me to consider writing an RFC?
What I DON’T Want to Know: opinions on specific syntax. Assume, for now, that it will be something sane. We can bikeshed on syntax later.
This isn't the only cost. There is a real cost to have too many choices to do very similar things. It's hard to pinpoint it to any one specific thing, but they add up.
With that said, I'm not really a fan. It could encourage writing shorter comments ("If I delete a few words I can inline this comment"), and I think the cases where it's reasonable to write short comments don't justify a new syntax altogether.
/// Kind of operation performed by a binary expression.
enum BinaryOperation {
/** Addition */ SUM,
/** Multiplication */ PRODUCT,
/** Exponentiation */ POWER,
/** Logarithm */ LOG,
};
That said, you could maybe make an argument that this could be covered by "inner" documentation:
/// Kind of operation performed by a binary expression.
enum BinaryOperation {
SUM, //! Addition
PRODUCT, //! Multiplication
POWER, //! Exponentiation
LOG, //! Logarithm
};
But... I'm rather bullish on this. This only saves space in very simple cases where the reader is unlikely to be overloaded anyway.
Given that we already have "attach to next" and "attach to context" doc comments, I don't think overloading "attach to next" to also mean "attach to previous" but only under some circumstances is a great idea. That's keeping the number of comment types simple at the cost of making how they work more complex; it's not a free win.
Another vote against this. I used to do this in C++ a lot and was told not to when I started with Rust. I really don’t miss the inline syntax; it saves a bit of vertical space at the cost of making edits trickier (especially when lengthening a comment beyond what fits on a single line).
What I would like sometimes is a simple way to add an empty comment to things which already document themselves well. Maybe for example:
/// Whether this thing is black or white
enum Colour {
/** */ Black,
/** */ White,
}
Nothing silly or dumb about what you said. What I espoused is what's called an "opinion"; people are allowed to have differing ones. No need to apologise.
I used to use comments like this, and I think it’s not worth it. I generally like the uniformity more than being able to squeeze few more lines on the screen here and there.
Squeezing code is underrated I don't like very-low-density C# code, I use a larger font and I prefer to not need to scroll some pages to understand any function that does something.
IMO the most intuitive version is ‘what D does’ listed above - I’d have guessed that to work out of the box. (’/// at the beginning of a line annotates what comes next, /// at the end of the line annotates whatever field/parameter that line defines’) The single line comments are very frequently used ‘after a line’.