Dear Rust developers/users,
I want to convince you that the current syntax for doc-comments in rust
is sub-optimal and should be re-worked.
Here is an example of a doc-comment in various languages:
Rust:
#[doc = "Some short description of what this function does"]
fn my_fun (x: int) -> int { ... }
Python:
def my_fun(x):
""" Some short description of what this function does """
Java:
/**
* Some short description of what this function does
*/
int myFun (int x) { ... }
I feel that the syntax for Rust is more complex than in Python/Java. The
programmer has more rules to follow when reading/writing it. The difference
is small, only a paper-cut, but please consider that:
1. Compared to Python/Java, it takes more effort to read/write Rust's
doc-comments
and therefore fewer people will do so.
2. When people are spending less effort on doc-comments then they can spend
more effort on their real job. Tasks that take less effort feel more
fun.
3. doc-comments are a frequently used part of the language, so a special
syntactic form is justified over using the generic attribute syntax.
Proposed solution:
I suggest that the current doc-comment syntax be replaced with:
/// ... (three slashes instead of two) for single line doc-comments
/** ... */ (two initial stars instead of one) for multi-line doc-comments
In this scheme doc-comments are just normal comments with some - very
lightweight - marker syntax that lets the programmer/text-editor know that
they are special. It is similar to Java and some C++ commenting standards.
Does this proposal have any hope?
Thanks
Gareth
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
