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.