Change default comment style for chpldoc?

[BryantLam]

Related #14250

Multi-line/block comments can be misidentified as a documentation comment. Should chpldoc change the default comment style?

Javadoc uses /**, though that can technically also be misinterpreted if users like doing something like:

/**************************************************
 *  Some long piece of
 *  text that goes here.
 **************************************************/

.. unless it's strictly interpreted as /**[whitespace|eol] which is okay too.

(Aside: I dislike multi-line/block comments because they don't nest [in C/C++] and it's easy to misread a complicated comment block if your editor lacks syntax highlighting.)

Doxygen uses /// or //!:

/// Read some data and return a custom opaque file handle.
///
FileHandle c_read_some_data(const char* filename) { ... }

[lydia-duncan]

We did consider using a distinct style at the time. If I remember correctly, we did not because:

• block comments were typically used for more in depth descriptions of a particular symbol, making them likely to be what the user wanted (rather than forcing the user to update their comments to a particular style). This meant that when we added support for documentation style, users could get a lot of documentation for free instead of having to adjust their code
  • It also meant we could get a lot of documentation for free when we started eating our own dog food and using it to provide library documentation.
• we wanted to encourage users to explicitly document their symbols, so the cases where no overriding documentation comment was present would hopefully cause them to realize "right, I should explicitly write something about this symbol to avoid having this useless info present"
• users that wanted a separate style could specify that with the flag changing the documentation comment style

@bradcray or @mppf should definitely correct me if they remember otherwise.

My main hesitancy with changing it is that it will be a lot of work to do, but I don't otherwise object.

[BryantLam]

• block comments were typically [emph] used for more in depth descriptions of a particular symbol, making them likely to be what the user wanted (rather than forcing the user to update their comments to a particular style).

Ironically, I never use block comments.

This meant that when we added support for documentation style, users could get a lot of documentation for free instead of having to adjust their code

I could see why this would be considered a feature, though I don't think it's overly burdensome to have users understand one more comment style (block comment, line comment, and doc comment -- whether block or line styling) versus overloading the block comment for two things and causing the now aforementioned ambiguity.

• It also meant we could get a lot of documentation for free when we started eating our own dog food and using it to provide library documentation.

My main hesitancy with changing it is that it will be a lot of work to do, but I don't otherwise object.

We all pay a price someday... :) chpldoc does let you change the comment styling, so changing the default now doesn't mean Chapel's documentation would necessarily be impacted.

[mppf]

(Aside: I dislike multi-line/block comments because they don't nest easily and it's easy to misread a complicated comment block if your editor lacks syntax highlighting.)

Chapel block comments do nest. for example

it's easy to misread a complicated comment block if your editor lacks syntax highlighting.

I'm not sure what you mean here. Usually I don't have trouble identifying the end of a comment block, but I agree that it's harder to do when the editor doesn't syntax highlight. (But then... isn't getting syntax highlighting in whatever environment you edit a better goal?)

[mppf]

I don't think this is the hill to die on, but I will give my 2 cents.

I like that

/* some doc comment */
proc bla() { }

will apply the comment as docs to the function. I would also be happy having

// some doc comment
proc bla() { }

also apply to a function for chpldoc by default.

I don't actually think that we need to have a special "docs comment" introduction. What problem does that actually solve?

If a function has some comments that aren't to be mistaken for a docs comment, they can:

• be moved just inside the function declaration (which makes sense when they are about the implementation, e.g.)
• be put in another comment just before the docs comment.

I think this "the last comment before the function is chpldoc" rule is easier to understand and remember than having different people use different docs-comment-introduction styles, personally.

(I used function above for concrete examples; but the rule also applies to modules, variables, etc).

[BryantLam]

It's odd to me and at odds with the convention of explicitly choosing when to document. Python has docstrings. The Javadocs (Java) + Doxygen style is used by C, C++, Swift, and Rust. I'm not saying Chapel's approach is wrong, but it is different.

If a function has some comments that aren't to be mistaken for a docs comment, they can ...

The opt-out behavior was a bit annoying to me when I ran into bug #14250 because I didn't know what was wrong. Turns out, some unrelated piece of code got commented out and it broke document generation. As a new user, I don't think I could have figured out why the behavior was occurring or how to fix it (but https://github.com/chapel-lang/chapel/issues/14250#issuecomment-540563325 would resolve it, so I'm not too bummed).

.. But I don't particularly care strong enough to insist on this change (though I would prefer it). I'm okay with not changing it not adding a new document comment if the approach is to make all comments into documenting comments.

[BryantLam]

Aside: is there another language that has the implicit documenting behavior?

[mppf]

From https://github.com/chapel-lang/chapel/issues/14250#issuecomment-541097036

Maybe what you are trying to say is that you think it's easier to remember to use a special form for docs comments than it is to remember something like "the last comment before it is the docs comment"?

Yes. The rest of your comment is a corollary to this statement. I guess what I'm saying is that it's harder to make a mistake -- or in this case -- forget about when a comment turns into a document comment if it is explicitly done by the user (/** or /// or //!, etc.).

It is indeed less likely that one would put a /** comment when commenting out code. (But, one could certainly still do it and be confused).

[BryantLam]

(But, one could certainly still do it and be confused)

That's true, though I would think significantly less likely. The parser could interpret a literal /** for doc comments and anything else wouldn't be allowed: (/******** is not a doc comment).

[lydia-duncan]

Python has docstrings

Python's docstrings are basically multiline comments, and Python doesn't otherwise support multiline comments. So you could say we're following Python's style, we just don't explicitly say multiline comments are only really for documentation purposes (because we think multiline comments are valuable in their own right)

[lydia-duncan]

For the record, when I first encountered documentation comments in Python, I assumed that was just how multiline comments were written (because all the other languages I'd used had multiline comments and because they didn't have a separate style for "not documentation multiline comments") rather than realizing that they were intended mostly for documentation and the multiline use case was a side-effect rather than their main intended purpose