# RustDoc use @ in comments

**URL:** <https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672>\
**Category:** language design\
**Created:** [November 2, 2022, 2:50pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672 "2022-11-02T14:50:49Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![hydroper1](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hydroper1/32/12099_2.png) [@hydroper1](https://internals.rust-lang.org/u/hydroper1)\
**Post date:** [November 2, 2022, 2:50pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/1 "2022-11-02T14:50:49Z")

</div>

Is it possible for RustDoc to turn:

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

```

into something like:

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

```

?

---

<div class="post-metadata">

**Author:** ![newpavlov](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/newpavlov/32/3290_2.png) [@newpavlov](https://internals.rust-lang.org/u/newpavlov)\
**Post date:** [November 2, 2022, 3:10pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/2 "2022-11-02T15:10:25Z")

</div>

I would prefer something like this instead:

```rust
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](https://github.com/rust-lang/rust/issues/57525)

---

<div class="post-metadata">

**Author:** ![notriddle](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/notriddle/32/14082_2.png) [@notriddle](https://internals.rust-lang.org/u/notriddle)\
**Post date:** [November 2, 2022, 3:22pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/3 "2022-11-02T15:22:03Z")

</div>

> [@hydroper1](#):
>
> ```rust
> /// @param a - Parameter description
> pub fn f(a: i64) {
> }
> 
> ```

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.

---

<div class="post-metadata">

**Author:** ![cuviper](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/cuviper/32/1897_2.png) [@cuviper](https://internals.rust-lang.org/u/cuviper)\
**Post date:** [November 2, 2022, 3:46pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/4 "2022-11-02T15:46:32Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![scottmcm](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/scottmcm/32/2355_2.png) [@scottmcm](https://internals.rust-lang.org/u/scottmcm)\
**Post date:** [November 2, 2022, 5:34pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/5 "2022-11-02T17:34:06Z")

</div>

Related issue:

> <https://github.com/rust-lang/rfcs/issues/2639#issuecomment-464423048>
>
> \[RFC 1574\](https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-docu…mentation-conventions.md) gives the following list of updated common headings:
> 
> \* Examples
> \* Panics
> \* Errors
> \* Safety
> \* Aborts
> \* Undefined Behavior
> 
> This list misses the formal parameters for function/method calls, as well as a description of what is returned. Can you please add \`Parameters\` and \`Returns\` as two more common headings?

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.

---

<div class="post-metadata">

**Author:** ![mjbshaw](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/mjbshaw/32/5103_2.png) [@mjbshaw](https://internals.rust-lang.org/u/mjbshaw)\
**Post date:** [November 2, 2022, 9:32pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/6 "2022-11-02T21:32:21Z")

</div>

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`](https://man7.org/linux/man-pages/man2/kill.2.html) is an easy example where documenting individual parameters could be useful.

---

<div class="post-metadata">

**Author:** ![scottmcm](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/scottmcm/32/2355_2.png) [@scottmcm](https://internals.rust-lang.org/u/scottmcm)\
**Post date:** [November 2, 2022, 9:55pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/7 "2022-11-02T21:55:09Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mjbshaw](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/mjbshaw/32/5103_2.png) [@mjbshaw](https://internals.rust-lang.org/u/mjbshaw)\
**Post date:** [November 2, 2022, 10:06pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/8 "2022-11-02T22:06:12Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\
**Post date:** [January 31, 2023, 10:07pm UTC](https://internals.rust-lang.org/t/rustdoc-use-in-comments/17672/9 "2023-01-31T22:07:04Z")

</div>

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