consider nudging people to document new features in the unstable book

[jyn514]

Location

https://doc.rust-lang.org/nightly/unstable-book/

Summary

right now, when you add a new unstable feature, unstable-book-gen will parse it out of the source code and generate a stub such as https://doc.rust-lang.org/nightly/unstable-book/language-features/async-trait-bounds.html.

do we actually want this? it seems nice to instead encourage people to write docs for the new features they add. i am imagining something like this (see https://github.com/rust-lang/rust/blob/d3a2440384b54664dddd56e0081ca094c444e869/src/doc/unstable-book/README.md for how this differs from how things currently work):

1. run unstable-book-gen as-is one last time. copy the generated SUMMARY.md to src/doc/unstable-book, so it's tracked by git.
2. change unstable-book-gen to not overwrite SUMMARY.md, merely generate a local copy. then, give a hard error if its generated SUMMARY differs from the one tracked by git.

the second thing requires people to write their own docs, even if they're just a stub. and hopefully while people are at it, they will take the time to write more docs than just a stub.

[jyn514]

cc #40694, #42454

the latter mentions library features; maybe we can generate stubs but only for library features and not lang?

[jyn514]

another option is to generate a stub, but only if we find a tracking issue for the feature, so we never have features that are completely undocumented.

[jyn514]

it would be nice to require unstable-book docs for features "on stabilization track", so everything but incomplete_features. that means we would end up with one of three states:

1. incomplete_feature, requires either a tracking issue or unstable-book docs
2. perma-unstable, requires unstable-book docs
3. regular feature, requires both a tracking issue and unstable-book docs

[lolbinarycat]

it would be nice to require unstable-book docs for features "on stabilization track", so everything but incomplete_features. that means we would end up with one of three states:

Where do experimental features fit in to this?

[lolbinarycat]

I also agree with lang features being more important to have in the unstable book, since library features always have api docs (it would be cool to have a way to tell exactly what functions were enabled by a library feature, though. i guess that would probably belong in rustdoc.)

[jyn514]

it would be nice to require unstable-book docs for features "on stabilization track", so everything but incomplete_features. that means we would end up with one of three states:

Where do experimental features fit in to this?

i don't know what experimental features are. i think treating them as either incomplete features (only tracking issue required) or normal features (both tracking and unstable docs required) could make sense depending on context.

[lolbinarycat]

features that have not yet gone through the relevant approval process (RFC/ACP)