Nouveau - Nov 2025 - [PATCH RFC 1/4] rust: clist: Add abstraction for iterating over C linked lists

You can use `cfg(doc)` and `cfg(doctest)` to only include parts of the
docs when running doctests (if that's what this is about).

Le mar. 4 nov. 2025 ? 15:07, Miguel Ojeda
<miguel.ojeda.sandonis at gmail.com> a ?crit :
>
> On Tue, Nov 4, 2025 at 2:42?PM Alexandre Courbot <acourbot at
nvidia.com> wrote:
> >
> > What I'm more worried about is that it might be a PITA to write.
:/ But
> > maybe the core folks have an example for how this could be done
cleanly
> > and in a reusable way (i.e. we don't want to duplicate the dummy
list
> > creation code for every example).
>
> Using a shared module/file may be good enough, as long as the `#[path
> = ...] mod ...;` or `include!(...)` is hidden with `#`, i.e. as long
> as the user does not need to see that to understand the example.
>
> But, yeah, we have already a few places in the tree with fake `mod
> bindings` for doctests and things like that.
>
> Cc'ing Guillaume in case there is a better way to do this. The
"have
> something applied to several parts of docs" has come up before for
> references too (the "external references map" I proposed).
>
> In any case, even if the example does not run, it is still way better
> to have it at least build instead of completely ignored, because that
> means it will not become stale.
>
> Cheers,
> Miguel

On Tue, Nov 4, 2025 at 3:35?PM Guillaume Gomez
<guillaume1.gomez at gmail.com> wrote:
>
> You can use `cfg(doc)` and `cfg(doctest)` to only include parts of the
> docs when running doctests (if that's what this is about).
Thanks for the quick reply!

I think this is more about having some code essentially "prefixed" to
certain doctests without having to repeat it in every one. Or, more
generally, to provide custom "environments" for certain doctests,
including perhaps a custom prelude and things like that.

So one way would be writing a `mod` (perhaps with a `path` attribute)
or an `include` to manually do that. Or perhaps having an auxiliary
crate or similar that contains those mods/files (that probably only
gets built when the KUnit doctests are enabled).

Orthogonally, the script that generates the doctests could perhaps
help to automate some of that. For instance, we could have a way to
specify an "environment" for a given Rust file or Rust `mod` or
similar, and then every doctests would have the code prefixed to them.
But I prefer to wait until we have real users of this and the new JSON
generation.

Using `cfg(doctest)` in some code in the `kernel` crate wouldn't work,
unless I am missing something, because we wouldn't want to have a
"parallel `kernel` crate" in the same build that only the doctests
would use.

Cheers,
Miguel