3 ms·

usefulness and readability of a well formatted block comment, especially for documentation generation it's indeed a bit strange the OP doesn't mention that as

by stinos 9y ago

usefulness and readability of a well formatted block comment, especially for documentation generation it's indeed a bit strange the OP doesn't mention that as an advantage, accoording to the OP the first main purpose is just that it is "perceived that line comments are impractical for long comments"

Athas 9y ago
Line comments are no hindrance to documentation generation. Extracting the contents from a paragraph line comment is a rather simple regular expression[0]. Haskell almost exclusively uses line comments for documentation, and it works fine. You write it like this (the '|' is to indicate that it's a doc-comment): -- | Compute this and that. -- Parameter @x@ is the good one, and -- parameter @y@ is the bad one. -- -- The function works well and runs in time -- proportional to $O(n**n**n**n)$. f x y = ...
- stinos 9y ago
  Actually my point was mainly about the readability aspect, should have made that more clear: for me there usually still is a (slight) advantage in readability if every line is not prefixed. E.g. the code you show here looks rather cluttered to me. It doesn't mean it does to you of course, if you are used to it your brain just ignores those dashes. But mine doesn't, since I am not used to it. Though it would probably take me only a couple of days.
chrismorgan 9y ago
Rust supports block comments and line comments; the recommended style is “don’t use block comments”. I have never felt any inclination to use block comments in Rust. These examples of doc comments (using slash-star-star or triple slash instead of slash-star or double slash which are plain comments) are all equivalent, and I know which one I find to be nicest (the third, with line comments): /** * This is documentation. * * It spans multiple paragraphs. */ pub fn foo() {} /** This is documentation. It spans multiple paragraphs. */ pub fn foo() {} /// This is documentation. /// /// It spans multiple paragraphs. pub fn foo() {} #[doc = "This is documentation."] #[doc = ""] #[doc = "It spans multiple paragraphs."] pub fn foo() {} (You can mix-and-match, too; I’ve combined doc attributes with cfg_attr before, to add doc comments if a certain feature is enabled, see the bonus section in https://chrismorgan.info/blog/rust-cfg_attr.html. https://chrismorgan.info/blog/rust-cfg_attr.html.)

by stinos 9y ago

Athas 9y ago

Line comments are no hindrance to documentation generation. Extracting the contents from a paragraph line comment is a rather simple regular expression[0]. Haskell almost exclusively uses line comments for documentation, and it works fine. You write it like this (the '|' is to indicate that it's a doc-comment): -- | Compute this and that. -- Parameter @x@ is the good one, and -- parameter @y@ is the bad one. -- -- The function works well and runs in time -- proportional to $O(n**n**n**n)$. f x y = ...

stinos 9y ago
Actually my point was mainly about the readability aspect, should have made that more clear: for me there usually still is a (slight) advantage in readability if every line is not prefixed. E.g. the code you show here looks rather cluttered to me. It doesn't mean it does to you of course, if you are used to it your brain just ignores those dashes. But mine doesn't, since I am not used to it. Though it would probably take me only a couple of days.

chrismorgan 9y ago

Rust supports block comments and line comments; the recommended style is “don’t use block comments”. I have never felt any inclination to use block comments in Rust. These examples of doc comments (using slash-star-star or triple slash instead of slash-star or double slash which are plain comments) are all equivalent, and I know which one I find to be nicest (the third, with line comments): /** * This is documentation. * * It spans multiple paragraphs. */ pub fn foo() {} /** This is documentation. It spans multiple paragraphs. */ pub fn foo() {} /// This is documentation. /// /// It spans multiple paragraphs. pub fn foo() {} #[doc = "This is documentation."] #[doc = ""] #[doc = "It spans multiple paragraphs."] pub fn foo() {} (You can mix-and-match, too; I’ve combined doc attributes with cfg_attr before, to add doc comments if a certain feature is enabled, see the bonus section in https://chrismorgan.info/blog/rust-cfg_attr.html. https://chrismorgan.info/blog/rust-cfg_attr.html.)