RustDoc use @ in comments

language design
1

Is it possible for RustDoc to turn:

/// @param a - Parameter description
pub fn f(a: i64) {
}

into something like:

/// # Parameters
/// - `a`: Parameter description
pub fn f(a: i64) {
}

?

1 Like
2

I would prefer something like this instead:

pub fn f(
    /// Parameter description
    a: i64,
) { ... }

// Alternatively:
pub fn f(
    a: i64, //! Parameter description
) { ... }

// This results in a compilation error:
pub fn f(
    /// Parameter description
    a: i64, b: i64,
) { ... }

UPD: Relevant Rust issue: rustdoc support for per-argument documentation · Issue #57525 · rust-lang/rust · GitHub

9 Likes
3

Nice idea, but I prefer @newpavlov's syntax.

Since the code you posted is already accepted by rustdoc without warning, changing what it does is complicated by the need to avoid breaking people's docs. Producing a syntax error on every line that starts with @ would be a breaking change, but not producing a syntax error if someone accidentally wrote @paarm would be unhelpful.

Embedding the structured data in Rust instead of embedding it in Markdown solves the problem, because, while Markdown essentially accepts anything, Rust rejects syntax that it doesn't understand. To design a feature that doesn't break existing code, use syntax that older versions of the compiler consider invalid.

3 Likes
4

The new "@param" syntax could be introduced in a new edition, but I think attaching the comment to the actual parameter is better anyway.

11 Likes
5

Related issue:

I'm really not a fan of this. It tends to result in unhelpful noise most of the time.

I care about documentation for public fields, but generally if someone's tempted to document a parameter, I think it's better to rename the parameter or make an options struct with documented fields/methods.

7 Likes
6

Documenting parameters can definitely be useful. Renaming typically isn't sufficient. Wrapping in a newtype or options struct is viral and disconnects the parameters from the function.

For example, kill is an easy example where documenting individual parameters could be useful.

4 Likes
7

I'm not a fan of referencing int(int,int) functions in C for saying that a feature is useful, especially when passing -1, 0, 1, and 10 do completely different things, like with that one.

1 Like
8

Okay, but these functions still exist. I'd like to be able to provide some good documentation in my FFI bindings, and I don't have a time machine to go back and change history to give them a better API.

Anyway, I don't want to get hung up on C functions. It's just a fairly trivial example.

1 Like
9

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.