pre-RFC: adding a "summary" short description to Cargo crates

#1

Cargo crates have a “description” field, which provides a detailed description of the crate. Some crates just fill in a short sentence or sentence fragment, while others provide a detailed multi-line description.

For the purposes of packaging Cargo crates for Linux distributions, I’d like to generate an appropriate package description. Both the .deb and .rpm package formats provide both a “summary”/“short description” that fits on one line, and a “long description” with multiple lines. A one-line summary makes sense in other contexts as well. I’d like to have some more useful metadata to construct that from, without having to attempt to parse out a short description from “description” or invent one downstream.

I’d like to propose extending Cargo metadata to include a “summary” field for a short description, limited to no more than 60 characters (allowing enough room to add things like the package name or a tag like " - source" without passing 80).

The existing “description” field can continue to provide an unrestricted long description. “description” would become optional for packages with a “summary”, if they don’t want to provide any more detail beyond the summary. For backward compatibility, “summary” would remain optional.

Does this seem reasonable?

#2

I understand the rationale, but it seems you’ll still need to have a way to generate a short description for crates that didn’t specify one, so I’m not sure how helpful this would be.

#3

If a crate has a sufficiently short description that already works as a summary, I’d use that; otherwise, rather than attempting to generate a short description from a longer description, I’d submit a patch upstream adding a summary to the crate. I’d much rather improve descriptions and summaries upstream than patch them downstream.

That seems preferable to assigning special semantics to the first line or sentence of the “description” field, and submitting patches upstream like “make the first sentence of the description shorter than 60 characters”.

#4

In general, providing more ways to give info about a crate on the crate’s crate.io page seems valuable. cc @carols10cents

#5

This seems totally reasonable to me.

#6

Since we also have the readme field pointing at a file, and the entire crate documentation (and especially the top-level crate docstring), another alternative might be to require description to be short and showing information from the readme and/or top-level documentation on crates.io?

Otherwise, having basically the same information in description, a readme, and a top-level docstring doesn’t seem very DRY.

#7

To be honest, I’m already tired of duplicating the same information in lib.rs, README.md, and Cargo.toml. I doubt I’d even bother with a fourth copy of the same damn thing (and having to remember to keep them all in sync with one another).

#8

Can a convention help save the day here? For example, Cargo.toml descriptions should always start with a short one sentence summary of the crate.

#9

@kaj That alternative would work, but Cargo couldn’t enforce it, because existing crates have descriptions that don’t fit. A new field would allow Cargo to set a length limit.

I do agree that the README works much better as a longer description than the description field does. So, perhaps it would make sense to encourage people to use summary and README, and skip description entirely.

@DanielKeep Good point; I wish we had a good way to de-duplicate lib.rs documentation and README.md. The description field shouldn’t need to duplicate those as well; as above, perhaps using only summary (for a brief summary) and README (for full documentation) would make sense.

@burntsushi A convention would help, but I don’t think Cargo can help maintain that convention, because many existing crates would have descriptions that don’t match it.

#10

@kaj’s solution sounds best to me. I don’t think we need to enforce that the description is short; as people are used to the README being rendered on their crates.io page, they will reduce the length of the description themselves.

It also sounds like @DanielKeep’s problem (syncing and duplicating documentation) could be solved by a tool which generates a README from your lib.rs doc comment or vice versa.

#11

@withoutboats That makes sense, though once we have the README inclusion working we might want to try for an advisory mechanism to tell people their description is too long.

Also, I don’t think a tool to generate README from lib.rs or vice versa would help, because you shouldn’t check generated files into git. I don’t think it makes sense to have both and keep them in sync; I think it makes sense to have some way to include part or all of the README content from the main crate documentation. (We can’t do the reverse since READMEs get read by users, github, etc. But we could teach rustdoc to incorporate README.)

#12

Not all crates want their READMEs to coincide with their main docs. Especially as libraries grow in popularity and size, the purpose of these files will diverge - a major library’s README will be targeted more at potential contributors, whereas the API docs are targeted squarely at users.

If you do want your README mirrored in your lib.rs, some script you can run as a githook seems sufficient. I don’t think the idea that you shouldn’t check generated files into git is applicable here.

#13

I use cargo-readme to generate my README.md from lib.rs. I use a template for slight customization.

@josh I generate the README anyway so that it shows up nicely on github for people visiting the page.

#14

I’d prefer the existing description field was changed to be the short summary. Take the first line or first n chars/words where needed. Display the actual readme file when long description is needed.

Editing of long text in toml is annoying. I strongly prefer a separate file, so any excuse to drop the long description is great for me :slight_smile: