rustdoc wanted features & bugfixes
#350
Comments
ojeda
added
• toolchain
Add a test case to assert that the skb->pkt_type which was set from the BPF program is retained from the netkit xmit side to the peer's device at tcx ingress location. # ./vmtest.sh -- ./test_progs -t netkit [...] ./test_progs -t netkit [ 1.140780] bpf_testmod: loading out-of-tree module taints kernel. [ 1.141127] bpf_testmod: module verification failed: signature and/or required key missing - tainting kernel [ 1.284601] tsc: Refined TSC clocksource calibration: 3408.006 MHz [ 1.286672] clocksource: tsc: mask: 0xffffffffffffffff max_cycles: 0x311fd9b189d, max_idle_ns: 440795225691 ns [ 1.290384] clocksource: Switched to clocksource tsc #345 tc_netkit_basic:OK #346 tc_netkit_device:OK #347 tc_netkit_multi_links:OK #348 tc_netkit_multi_opts:OK #349 tc_netkit_neigh_links:OK #350 tc_netkit_pkt_type:OK Summary: 6/0 PASSED, 0 SKIPPED, 0 FAILED Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/r/20240524163619.26001-4-daniel@iogearbox.net Signed-off-by: Alexei Starovoitov <ast@kernel.org>
Any progress on that? I've been working on rustdoc, and recently I've been cleaning up a few things in the intra-doc link system. |
|
Not yet -- I will eventually get to it, since we are definitely interested in it. I have had a few more ideas around it. If you have time to put into it, please let me now! |
|
I have plenty of time, the limitation is actually if t-rustdoc has enough time to review the contributions! being able to say "rust4linux wants it" would probably help a fair bit towards getting it prioritized, though. |
|
That makes sense, yeah. If you have a lot of time, and want to work on the feature, then please go ahead (and thanks a lot!), it will be a while until I can put time into that due to other priorities. I am happy to help or co-author or something like that. If what you want is write code rather than the RFC, then I think for a feature like that having a prototype implementation could also help. Please feel free to contact me by email or in the Rust or Rust for Linux Zulips. |
Note: there is the "A-rust-for-linux" label in the
rustrepository: 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.: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.:An alternative could have been to use:
with a
references.mdfile with: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.: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.rustdoclint to flag potential intra-doc links rust-lang/rust#131510.Documentation under conditional compilation.
allyesconfigconfiguration (or similar) generated for each architecture.Custom logo/favicon flag (for local/bundled image files).
Nice to have (not critical, we could workaround if needed, etc.)
Collapsed-by-default (or switch) for uncommon/advanced APIs.
allocif fallible allocations were to be added (try_*).Switch for private/hidden items documentation.
--document-private-itemsand--document-hidden-items, but at runtime.doc_cfg,auto_doc_cfg,cfg_hide.External
doc(cfg(...))map file (customization in general of the rendered banner).doc(cfg(...))rust-lang/rust#87139.Add copy button for code blocks.
Low priority (we will likely not use them in the end)
Done (stabilized, fixed, not needed anymore, etc.)
Jump to definition (i.e. links in source view,
--generate-link-to-definition).rustdoc @argfile.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.)
superin doctests errors.superin doctests errors rust-lang/rust#130274.Low priority (we will likely not use them in the end)
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.rustdoc::broken_intra_doc_linksbehavior change withmacro_rulesnot in scope since 1.63 rust-lang/rust#106142.ICE:
rustdoc's--testoption may callrustcwith too many arguments.rustdoc's--testoption may callrustcwith too many arguments rust-lang/rust#122722.rustdoc --test: Prevent reaching the maximum size of command-line by using files for arguments if there are too many rust-lang/rust#122840 (1.79).The text was updated successfully, but these errors were encountered: