Guidelines for documenting intended vs actual behavior #2037
Description
I think the authoring guide should have some guidance on whether to document the actual behavior of rustc vs the intended behavior, and how to handle known bugs.
If there is a known issue, should it be encouraged or discouraged to link to the GitHub issue?
Should it have specific callouts for future-incompatible warnings? How should these known problems be documented? Should it document how it is intended to work? What if the intention is not yet known?