Matthew Wilcox [off-list ref] writes:

If we're going to talk about incorporating Rust into the doc system, we
should probably include some Rust folks - thus, I'm adding Miguel.

On Thu, Mar 25, 2021 at 04:30:32PM -0600, Jonathan Corbet wrote:

quoted

Matthew Wilcox [off-list ref] writes:

We did come to the mutual agreement that teaching kernel-doc to parse
Rust code as well was not an ideal solution.  Probably there will be
some sort of tool to translate between rustdoc and our sphinx setup.
Beyond that, we'll see how it goes.

In the spirit of groping around for the best solution, I did some looking
around at various options, including using rustdoc for .c files (that
uses Markdown, which appears to be strictly worse than rST for our
purposes).

So here's my "modest proposal":

 - Similar to our ".. kernel-doc::" invocation in .rst files, handle
   ".. rustdoc::" (insert weeks of hacking here)
 - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
   does, but interprets a different style of comment and actually does
   most of the repetitive boring bits for you.

For example, xa_load:

/**
 * xa_load() - Load an entry from an XArray.
 * @xa: XArray.
 * @index: index into array.
 *
 * Context: Any context.  Takes and releases the RCU lock.
 * Return: The entry at @index in @xa.
 */
void *xa_load(struct xarray *xa, unsigned long index)

//rST
// Load an entry from an XArray.
//
// :Context: Any context.  Takes and releases the RCU lock.
// :Return: The entry in `xa` at `index`.
void *xa_load(struct xarray *xa, unsigned long index)

(more complex example below [2])

Things I considered:

 - Explicitly document that this is rST markup instead of Markdown or
   whatever.
 - Don't repeat the name of the function.  The tool can figure it out.

That worries me a wee bit just because a common source of problems is
kerneldoc comments becoming separated from the functions they describe
over time.  We finally have tooling to notice that; this seems like a
step in the other direction.

 - Don't force documenting each parameter.  Often they are obvious
   and there's really nothing interesting to say about the parameter.
   Witness the number of '@foo: The foo' (of type struct foo) that we
   have scattered throughout the tree.  It's not that the documenter is
   lazy, it's that there's genuinely nothing to say here.

...another failure mode is developers adding parameters and not
documenting them; this would mask that problem too.

 - Use `interpreted text` to refer to parameters instead of *emphasis* or
   **strong emphasis**.  The tool can turn that into whatever markup
   is appropriate.
 - Use field lists for Context and Return instead of sections.  The markup
   is simpler to use, and I think the rendered output is better.

[1] by which i mean "in a completely different way from, but similar in
    concept"

[2] More complex example:

/**
 * xa_store() - Store this entry in the XArray.
 * @xa: XArray.
 * @index: Index into array.
 * @entry: New entry.
 * @gfp: Memory allocation flags.
 *
 * After this function returns, loads from this index will return @entry.
 * Storing into an existing multi-index entry updates the entry of every index.
 * The marks associated with @index are unaffected unless @entry is %NULL.
 *
 * Context: Any context.  Takes and releases the xa_lock.
 * May sleep if the @gfp flags permit.
 * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
 * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
 * failed.
 */
void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)

//rST
// Store an entry in the XArray.
//
// After this function returns, loads from `index` will return `entry`.
// Storing into an existing multi-index entry updates the entry of every index.
// The marks associated with `index` are unaffected unless `entry` is ``NULL``.
//
// :Context: Any context.  Takes and releases the xa_lock.
//    May sleep if the `gfp` flags permit.
// :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
//    cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
//    failed.
void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)

Thanks,

jon