Provide mechanism for documenting known bugs or shortcomings

86e8f11
Opened by Jon Gjengset at 2024-11-07 23:27:31

Go has a fairly poorly documented feature that lines marked with BUG are shown under "Bugs" in documentation for a package. The keywords can be configured using the (again poorly documented) -notes argument to godoc. This can be used to document known bugs and shortcomings of a package alongside the package's main documentation. For examples, see the bottom of net, sync/atomic, or encoding/xml.

Having a similar feature in rustdoc would be really useful, as it establishes a standard way of communicating known problems, which could prevent unnecessary bug reports, and encourage dialogue about known limitations. If it were also possible to link to the discussion for a given feature or bug, that would make it even better.

Thoughts?

  1. Triage: no changes

    Steve Klabnik at 2019-12-25 17:26:35

  2. It's worth noting that go documentation is plain text, not markdown.

    is there anything this can do that having a # Bugs section can't?

    lolbinarycat at 2024-11-07 23:27:31