Add doc comments and doctests to `lib.rs` generated by `cargo init`

[sorairolake]

Problem

Currently, lib.rs generated by cargo init (or cargo new) has no doc comments and doctests.

cargo/src/cargo/ops/cargo_new.rs

Lines 877 to 880 in 5946db3

	b"\
	pub fn add(left: u64, right: u64) -> u64 {
	left + right
	}

I think it would be better if the add function had doc comments and doctests. I think these are useful examples of what happens when we run cargo doc and cargo test.

Proposed Solution

Add doc comments and doctests like this:

/// Calculates `left` + `right`.
///
/// # Examples
///
/// ```
/// let result = add(2, 2);
/// assert_eq!(result, 4);
/// ```
pub fn add(left: u64, right: u64) -> u64 {

Notes

No response

[epage]

Not a "no" but a "we have to tread carefully": cargo new tries to fill a lot of different roles

• Teach users about features: where this can be helpful
• Quickly setup a project: the more users have to delete, the worse this becomes

e.g. in #13371 we shifted that balance a little by making the link for more information transient so there would be less to delete.

[asasine]

In that vein, what about an --empty-lib option? Folks who use cargo more regularly would likely be aware of and reach for it, saving the pain of deleting a lot of boilerplate. Tutorials and docs like the books can continue recommending --lib since it's more relevant for those early in their learning.

[weihanglo]

what about an --empty-lib option?

That still adds an extra step for those users, since they have to remember one more thing. It’s no worse than expanding the template, but I wouldn’t say it’s better either. A flag in Cargo CLI has a more strict stability guarantee than the template itself.

Personally, I’m fine with adding a doc comment like this, though I’m not sure where to draw the line on adding more.

[epage]

When we discussed this as a team, it was pointed out that the --lib template basically needs to be deleted anyways so deleting the doc comment doesn't really change that.

We do have an open question of how much content is appropriate and how to prioritize what to show. We generally lean towards "a screen full" though whose screen is unsure.

I did post to https://rust-edu.zulip.cs.pdx.edu/#narrow/stream/75-t-devtools/topic/.60cargo.20new.60.20adding.20doc.20comments.3F/near/80913 to see if I could get feedback from educators.

[BartMassey]

My personal preference would be for an empty lib template. Generally, by the time folks start writing lib crates they know what needs to go in them. In terms of the stuff I've taught, I don't teach building lib crates until fairly late, so the template is not all that helpful.

All of that said, I think adding a one-line doc comment is probably best if we keep the template. I get diligently following the crate guidelines and providing an example of examples, but I think there's no need to give an example for the add() function.

[jedbrown]

Is the proposal to have both doctest and #[test] below that test the same thing, or to move the existing test to a doctest?

1. I like the motivation.
2. It's useful to see both ways to write tests and deleting everything is easy enough.
3. Editor/rust-analyzer features are richer when not inside a comment block.
4. If a user starts modifying the original function to their own, redundant tests will be irritating.

I'd lean toward adding a one-line doc comment, but not adding a test. I think redundancy is too irritating and having a test that doesn't name the function add (like just assert!(true)) would be confusing.

[epage]

The current thought is to add the doctest and keep the #[test]. We were thinking we could separately evaluate whether to remove the #[test].

[joshtriplett]

A big part of why we add the test is to help new users understand that tests exist and are built in.

I think there's value in continuing to do that.

[asasine]

I agree with this. I also think there's considerable value in demonstrating that rustdoc exists and is built in. It really does separate rust from other players (doxygen 😰)