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 😰)

[jedbrown]

Any ideas to mitigate the issue of tests being redundant, so that when the add function is edited, they don't have to manually update/delete two duplicate tests? There could be two functions, like add and square, one with a doctest and one with #[test], but that's a few more lines.

[BartMassey]

I use cargo new --lib literally 100 times a year. It's a very tiny inconvenience to delete a little Rust library tutorial every time I do this, but I will admit to being tired of it.

Perhaps the right compromise is to do what was finally (thank you for this) done for the comment link in Cargo.toml: remove the template entirely, and instead print a link to a good Rust library tutorial when cargo new --lib is invoked? Failing that, a one-line comment like the old Cargo.toml one linking to such a tutorial?

I that most users using cargo new --lib either know roughly what they are doing or do not understand that they should be using cargo new --bin instead. Binary crates are the natural starting point for new Rustaceans.

One counterargument is that doctests are currently not run for binary crates by cargo test. This is kind of terrible, especially since they are silently not run and my students thus believe that they are passing. If an add() test is going to be anywhere, it should be a doctest rather than a standalone test: this is the new thing for lib crate authors.