Skip to content

Allow multiple aliases in one doc(alias) attribute #81205

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Closed
jplatte opened this issue Jan 20, 2021 · 1 comment · Fixed by #82846
Closed

Allow multiple aliases in one doc(alias) attribute #81205

jplatte opened this issue Jan 20, 2021 · 1 comment · Fixed by #82846
Labels
A-attributes Area: Attributes (`#[…]`, `#![…]`) A-doc-alias Area: `#[doc(alias)]` C-feature-request Category: A feature request, i.e: not implemented / a PR. T-lang Relevant to the language team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@jplatte
Copy link
Contributor

jplatte commented Jan 20, 2021

It would be nice to be able to specify multiple aliases in one #[doc(alias)] attribute (as an array). This would be particularily useful for crates that export multiple derive macros with different sets of attributes. With #[doc(alias)], these can make the derive macro findable by any of its attributes names, e.g. serde could do sth. like

#[doc(alias = "default")]
#[doc(alias = "deny_unknown_fields")]
#[doc(alias = "untagged")]
#[doc(alias = "...")]
pub trait Deserialize<'de>: Sized { /* ... */ }

#[doc(alias = "into")]
#[doc(alias = "getter")]
#[doc(alias = "untagged")]
#[doc(alias = "...")]
pub trait Serialize { /* ... */ }

but needing one attribute / line for every attribute gets a bit unwieldy. This would be better:

#[doc(alias = ["default", "deny_unknown_fields", "untagged", "...")]
pub trait Deserialize<'de>: Sized { /* ... */ }

#[doc(alias = ["into", "getter", "untagged", "..."])]
pub trait Serialize { /* ... */ }
@camelid camelid added A-doc-alias Area: `#[doc(alias)]` C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-attributes Area: Attributes (`#[…]`, `#![…]`) T-lang Relevant to the language team, which will review and decide on the PR/issue. labels Jan 23, 2021
@GuillaumeGomez
Copy link
Member

From the attribute syntax I can see from https://doc.rust-lang.org/reference/attributes.html#meta-item-attribute-syntax, the [] syntax doesn't seem like a good idea. Instead I simply suggest:

#[doc(alias("into", "getter", "untagged", "..."))]
#[doc(alias = "into")]
pub trait Serialize { /* ... */ }

Accepting both syntaxes seems like a good compromise. Well, I'll open a PR and we can debate over the syntax there.

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Mar 19, 2021
…n514

rustdoc: allow list syntax for #[doc(alias)] attributes

Fixes rust-lang#81205.

It now allows to have:

```rust
#[doc(alias = "x")]
// and:
#[doc(alias("y", "z"))]
```

cc `@jplatte`
r? `@jyn514`
@bors bors closed this as completed in 61372e1 Mar 19, 2021
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
A-attributes Area: Attributes (`#[…]`, `#![…]`) A-doc-alias Area: `#[doc(alias)]` C-feature-request Category: A feature request, i.e: not implemented / a PR. T-lang Relevant to the language team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants