Use the following to include your README in your `doctest`s (so that your examples in your README are also executed).

#[doc = include_str!("../README.md")]
#[cfg(doctest)]
pub struct ReadmeDoctests;

See here:
doc.rust-lang.org/rustdoc/docu

Follow

Instead of using
//! my first line
//! my second line
//! my third line
for crate-level documentation, do this:
/*!
my first line
my second line
my third line
*/

☺️ 😌

· · Web · 1 · 0 · 0

@janriemer I thought single-line comments were preferred in general in Rust.

@josias Oh, thanks, I didn't know that.
I use the multi-line form in this case, because VS Code with rust-analyzer doesn't autocomplete the comment marker (//!) when inserting a new line.🙄

With struct-method-level comments (///) it works (I think?), so in this case I use single-line comments, just not for //!
(maybe I should create an issue? :rust_thinking:)

BurntSushi also does multi-line comments with //!, so can it be wrong?😄
See here: github.com/BurntSushi/rust-csv

@janriemer They both exist, so it makes sense to use the right one for the right situation. I just thought I read somewhere that single-line comments were preferred. I can't find anything authoritative on it. I think it's just a convention.

@josias Yes, you are probably right that they are prefered, because I've seen them in many other popular crates as well.👍

I wonder, what's the reason behind it, though.🤨

IMO, multi-line-comments are far easier to write than single-line-comments, when you have an essay of text - I mean, it is literally in the name ("multi-line").

@janriemer I know Zig doesn't have multi-line comments because they want the language to have context-free grammar. You can also tell if a section is commented or not based on the beginning of the line instead of having to find the opening and closing comment indicators. (which of course isn't a big deal when you use syntax highlighting)

@josias Oh, interesting that Zig doesn't have them.
Yes, regarding recognizability of comments, single-line comments are probably better, especially for visually impaired people, where syntax highlighting won't help.

Sorry for the late reply, I forgot to respond here.😊

Sign in to participate in the conversation
Mastodon for Tech Folks

This Mastodon instance is for people interested in technology. Discussions aren't limited to technology, because tech folks shouldn't be limited to technology either!