Description
Note: there is the "A-rust-for-linux" label in the rust repository: https://github.com/rust-lang/rust/labels/A-rust-for-linux.
Features that we would like to see
Required (we almost certainly want them)
-
External references map file.
-
The idea is to be able to write intra-doc-like links that point to external resources, e.g.:
/// Uses the kernel's C [`struct mutex`].where the URL is automatically provided, e.g. to some C documentation. Similarly, it could be use to avoid duplicating URLs that need to be manually updated, e.g. like a BibTeX database file. For instance, references to external articles, page/webs, papers, Wikipedia entries, etc.
To define those links,
rustdoccould be given a "external references" file containing a map of (term, URL) pairs (e.g. in a JSON or Markdown-references-like file with one reference per line), possibly passed via the CLI, e.g.:--external-references-file books.json
That way, the user is the one that defines the links and terms, possibly exporting them from other tooling (such as a documentation tool for another programming language).
Multiple files could also be allowed -- having different files for different topics/categories of references may be useful/cleaner for users.
An interesting extension could be to allow references to contain extra metadata (i.e. not just the URL), like in BibTeX.
rustdoccould then potentially render that metadata somehow, like Wikipedia's references (e.g. when clicking them, or when clicking a small information button close to the link, or as a footnote, or on hover...). Another possibility is that, even without any extra metadata,rustdoccould also decide to render them differently than "normal links".There is potential for ambiguity with existing links. Possibly a syntax could be provided to disambiguate (whether required in all cases or just in cases of ambiguity), as suggested by @aDotInTheVoid, e.g.:
/// Uses the kernel's [extern@`struct mutex`].Currently (Rust 1.78), when one uses an intra-doc link that matches a Markdown one (i.e. the intra-doc link title is the same as the Markdown link label of a link reference definition),
rustdocrenders it as the Markdown link, rather than the intra-doc link, without warning, e.g.:/// This ambiguous link ([`ThisModule`]) goes to the website, not to the Rust item. /// /// [`ThisModule`]: https://rust-for-linux.com
An alternative could have been to use:
--markdown-after-content references.md
with a
references.mdfile with:[Wikipedia]: https://www.wikipedia.org
but currently (Rust 1.78) those references cannot be used from elsewhere. Instead, a potential
--markdown-after-every-itemcould work.Similarly, including the references via
include_str!as suggested by @jyn514 works, e.g.:/// Here are all the docs, with [Wikipedia] links. /// #[doc = include_str!("references.md")]
but requires doing so in each case/item (rather than globally).
-
Status: Idea seemed reasonable to maintainers, RFC to be written.
-
Cc: @aDotInTheVoid, @GuillaumeGomez, @jyn514.
-
-
rustdoclint to flag potential intra-doc links. -
Documentation under conditional compilation.
- The kernel has a lot of configuration options and it would be useful to have a way to generate the docs independently of the particular kernel configuration.
- A partial workaround is having an
allyesconfigconfiguration (or similar) generated for each architecture. - Issue: Rustdoc needs to handle conditional compilation somehow rust-lang/rust#1998.
- Issue: Portability of documentation rust-lang-nursery/portability-wg#8.
-
Custom logo/favicon flag (for local/bundled image files).
- RFC: RFC: Custom logo/favicon command-line flags rust-lang/rfcs#3226.
- Alternative via another RFC (Bundle local images in rustdoc output rust-lang/rfcs#3397): RFC: Custom logo/favicon command-line flags rust-lang/rfcs#3226 (comment).
- The workaround broke once in 1.76 (RFC: Custom logo/favicon command-line flags rust-lang/rfcs#3226 (comment)).
Nice to have (not critical, we could workaround if needed, etc.)
-
Collapsed-by-default (or switch) for uncommon/advanced APIs.
- As a potential way to reduce the burden for most readers/users of
allocif fallible allocations were to be added (try_*).
- As a potential way to reduce the burden for most readers/users of
-
Switch for private/hidden items documentation (and
/* private fields */).- i.e. like
--document-private-itemsand--document-hidden-items, but at runtime. - Rather than having to render the docs twice and then providing a custom UI to the user to switch between the two.
- PR: rustdoc: add private items toggle rust-lang/rust#141299.
- Cc: @lolbinarycat.
- i.e. like
-
Private documentation (perhaps as an extension of the private items/fields toggle).
-
See rustdoc: add private items toggle rust-lang/rust#141299 (comment).
Before I forget, "one more thing" that is probably out of scope but related to this toggle: we could consider having a way to write "private documentation", e.g. in the Linux kernel we sometimes have private invariants that we put currently in the documentation in their own section (
# ...), but are really an implementation detail that ideally would go in a "private section of the docs". Using normal comments means we lose some features (e.g. nice rendered docs, intra-doc links, etc.), sadly. If we had that, this toggle could also show/hide that.
-
-
doc_cfg,auto_doc_cfg,cfg_hide. -
External
doc(cfg(...))map file (customization in general of the rendered banner). -
Add copy button for code blocks.
Low priority (we will likely not use them in the end)
-
Being able to use intra-doc links in "normal" comments.
-
In documentation, we write things like:
/// See [`SomeType`]. fn f() { // ... }
The idea is to be able to write the same in normal comments:
// See [`SomeType`].This includes things like
// SAFETYcomments, which tend to refer to types and functions/methods, e.g.:// SAFETY: This pointer comes from `Arc::into_raw` and we've been given back ownership. let boxed = unsafe { KBox::from_raw(ptr) };
// SAFETY: It is safe to send `Arc<T>` to another thread when the underlying `T` is `Sync` ... unsafe impl<T: ?Sized + Sync + Send> Send for Arc<T> {}
The potential advantages would be that:
-
rustdoccould give an error if the link does not exist, just like it does for the documentation, so preventing typos and missing changes in refactors etc. (we had a case of that recently). -
rustdoc(and IDE tooling) could provide clickable links for those in the source view. -
It would be more consistent with normal docs, which simplifies e.g. copy-pasting from one to the other.
-
-
-
Strip blank lines on both the top and the bottom sides.
Done (stabilized, fixed, not needed anymore, etc.)
-
Jump to definition (i.e. links in source view,
--generate-link-to-definition).- Moved to main list since we started using it.
-
rustdoc @argfile. -
rustdoc --emit=dep-info=....
Bugs that we would like to see fixed
Required (we almost certainly want them)
Nice to have (probably not critical, we could workaround if needed, etc.)
- Using
superin doctests errors.
Low priority (we will likely not use them in the end)
- Inconsistent number of blank lines rendered top/bottom.
Done (stabilized, fixed, or not needed anymore, etc.)
-
Avoid requiring an absolute path for the target spec file.
-
broken_intra_doc_linksbehavior change withmacro_rulesnot in scope since 1.63.- Issue:
rustdoc::broken_intra_doc_linksbehavior change withmacro_rulesnot in scope since 1.63 rust-lang/rust#106142. - Issue: Remove rustdoc intra-doc-link macro resolution fallback rust-lang/rust#110879.
- PR: refactor(docs): remove macro resolution fallback rust-lang/rust#110881.
- It turns out the new behavior is intended, and the fact that the links still got generated was just a compatibility measure for docs.rs, which will go away in Rust 1.71.
- Issue:
-
ICE:
rustdoc's--testoption may callrustcwith too many arguments. -
ICE documenting
compiler_builtins.rswith--remap-path-prefix.- Our workaround is to skip the flag only for
rustdoc. - Issue: ICE:
rustdoc: attempted to remap an already remapped filename rust-lang/rust#138520. - PR: Fix ICE: attempted to remap an already remapped filename rust-lang/rust#138556 (1.87).
- Lore: https://lore.kernel.org/rust-for-linux/CANiq72ntZj10H1DBqRyX=uLertMw59e=PM7ESVJ0zWfu_ECnnA@mail.gmail.com/.
- Patch: https://lore.kernel.org/rust-for-linux/[email protected]/.
- Our workaround is to skip the flag only for