Any interest in same-line Doc-Comments?

[insaneinside]

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
};

Previous RFCS:

• bstrie’s “Six forms of doc comments are five too many”: in which bstrie argues that Rust newcomers can’t handle (all) the Comments.
• nrc’s “Remove some kinds of doc comments”: in which bstrie calls the topic a “dreadfully bruised horse carcass.”

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.

[burntsushi]

Cost: code to support the style will need to be maintained.

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.

[leonardo]

Can’t you use a syntax like this, and keep things simple? (This is D syntax too, by the way)

/// Kind of operation performed by a binary expression.
enum BinaryOperation {
   SUM,      /// addition
   PRODUCT,  /// multiplication
   POWER,    /// exponentiation
   LOG       /// logarithm
}

[DanielKeep]

Well, you kind-of already can:

/// 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.

Can’t you use a syntax like this, and keep things simple?

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.

[dhardy]

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,
}

[leonardo]

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.

Lately I am asking/saying lot of silly/dumb things around here, thank you for the patience…

[DanielKeep]

Lately I am asking/saying lot of silly/dumb things around here

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.

[dpc]

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.

[leonardo]

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.

[starblue]

I dislike line-end comments:

• The lack of space adds pressure to leave out necessary details
• It adds pressure towards too long lines
• I like to globally rename things (good names are important), this scrambles the indentation of line-end comments

[kornel]

Yes, I’m interested in this. I prefer this style of comment, especially for C-like enums which already have the value on the same line.

When I created Rust wrapper for LCMS2 it was annoying to have to change this nice, readable, compact form:

mm2/Little-CMS/blob/d41071eb8cfea7aa10a9262c12bd95d5d9d81c8f/include/lcms2.h#L281-L320

To this long mess:

pornel/rust-lcms2-sys/blob/f787021bd3740b56ef1ebce9b0f9e9a00641c8b4/src/ffi.rs#L84-L157

[dobkeratops]

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’.

[system]

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.