From 01bdfefbf279f88cc53deffee0c966db67050782 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 30 Jun 2021 22:17:09 -0700 Subject: [PATCH 1/5] Add a doc alias policy Based on discussion in 2021-06-30 libs meeting. --- src/SUMMARY.md | 5 ++++ src/documentation/doc-alias-policy.md | 35 +++++++++++++++++++++++++++ src/documentation/summary.md | 1 + 3 files changed, 41 insertions(+) create mode 100644 src/documentation/doc-alias-policy.md create mode 100644 src/documentation/summary.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 68dafbd..6664b2a 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -36,6 +36,11 @@ --- +- [Documentation](./documentation/summary.md) + - [doc alias policy](./documentation/doc-alias-policy.md) + +--- + - [Tools and bots](./tools-and-bots/summary.md) - [`@bors`](./tools-and-bots/bors.md) - [`@rust-timer`](./tools-and-bots/timer.md) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md new file mode 100644 index 0000000..ac56a86 --- /dev/null +++ b/src/documentation/doc-alias-policy.md @@ -0,0 +1,35 @@ +doc alias policy +================ + +Rust's documentation supports adding aliases to any declaration (such as a +function, type, or constant), using the syntax `#[doc(alias = "name")]`. We +want to use doc aliases to help people find what they're looking for, while +keeping those aliases maintainable and high-value. This policy outlines the +cases where we add doc aliases, and the cases where we omit those aliases. + +- We must have a reasonable expectation that people might search for the term + in the documentation search. Rust's documentation provides a name search, not + a full-text search; as such, we expect that people may search for plausible + names, but that for more general documentation searches they'll turn to a web + search engine. + - Related: we don't expect that people are currently searching Rust + documentation for language-specific name from arbitrary languages they're + familiar with, and we don't want to add that as a new documentation search + feature; please don't add aliases based on your favorite language. Those + mappings should live in separate guides or references. We do expect that + people might look for the Rust name of a function they reasonably expect to + exist in Rust (e.g. a system function or a C library function), to try to + figure out what Rust called that function. +- The proposed alias must be a name we would plausibly have used for the + declaration. For instance, `delete` for `remove`, or `popcnt` and `popcount` + for `count_ones`, or `umask` for `mode`, or `mkdir` for `create_dir`. This + feeds into the reasonable expectation that someone might search for the name + and expect to find it ("what did Rust call `mkdir`"). +- There must be an obvious single target for the alias that is an *exact* + analogue of the aliased name. We will not add the same alias to multiple + declarations. We will also not add an alias for a function that's only + somewhat similar or related. +- The alias must not conflict with the actual name of any existing declaration. +- As a special case for stdarch, aliases from exact assembly instruction names + to the corresponding intrinsic function are welcome, as long as they don't + conflict with other names. diff --git a/src/documentation/summary.md b/src/documentation/summary.md new file mode 100644 index 0000000..1fb6e93 --- /dev/null +++ b/src/documentation/summary.md @@ -0,0 +1 @@ +- [doc alias policy](./doc-alias-policy.md) From 8715f19f57fc1739f6d1ee74b39d8d2683e26ea4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Fri, 2 Jul 2021 00:31:39 -0700 Subject: [PATCH 2/5] Note that `const` and non-`const` versions of the same function are fine --- src/documentation/doc-alias-policy.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index ac56a86..fa730d2 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -27,8 +27,9 @@ cases where we add doc aliases, and the cases where we omit those aliases. and expect to find it ("what did Rust call `mkdir`"). - There must be an obvious single target for the alias that is an *exact* analogue of the aliased name. We will not add the same alias to multiple - declarations. We will also not add an alias for a function that's only - somewhat similar or related. + declarations. (`const` and non-`const` versions of the same function are + fine.) We will also not add an alias for a function that's only somewhat + similar or related. - The alias must not conflict with the actual name of any existing declaration. - As a special case for stdarch, aliases from exact assembly instruction names to the corresponding intrinsic function are welcome, as long as they don't From 27898ab76c707439047b7a35fbac3d860ccd61a2 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 7 Jul 2021 11:18:55 -0700 Subject: [PATCH 3/5] Drop `delete` example; give example of `rmdir` instead --- src/documentation/doc-alias-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index fa730d2..7830792 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -21,10 +21,10 @@ cases where we add doc aliases, and the cases where we omit those aliases. exist in Rust (e.g. a system function or a C library function), to try to figure out what Rust called that function. - The proposed alias must be a name we would plausibly have used for the - declaration. For instance, `delete` for `remove`, or `popcnt` and `popcount` - for `count_ones`, or `umask` for `mode`, or `mkdir` for `create_dir`. This - feeds into the reasonable expectation that someone might search for the name - and expect to find it ("what did Rust call `mkdir`"). + declaration. For instance, `rmdir` for `remove_dir`, or `popcnt` and + `popcount` for `count_ones`, or `umask` for `mode`, or `mkdir` for + `create_dir`. This feeds into the reasonable expectation that someone might + search for the name and expect to find it ("what did Rust call `mkdir`"). - There must be an obvious single target for the alias that is an *exact* analogue of the aliased name. We will not add the same alias to multiple declarations. (`const` and non-`const` versions of the same function are From 339b3fe0dcf828cdccd29fc9fb6f2efa28aa117f Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 7 Jul 2021 11:21:56 -0700 Subject: [PATCH 4/5] Reorder examples --- src/documentation/doc-alias-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index 7830792..0d3dd05 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -21,10 +21,10 @@ cases where we add doc aliases, and the cases where we omit those aliases. exist in Rust (e.g. a system function or a C library function), to try to figure out what Rust called that function. - The proposed alias must be a name we would plausibly have used for the - declaration. For instance, `rmdir` for `remove_dir`, or `popcnt` and - `popcount` for `count_ones`, or `umask` for `mode`, or `mkdir` for - `create_dir`. This feeds into the reasonable expectation that someone might - search for the name and expect to find it ("what did Rust call `mkdir`"). + declaration. For instance, `mkdir` for `create_dir`, or `rmdir` for + `remove_dir`, or `popcnt` and `popcount` for `count_ones`, or `umask` for + `mode`. This feeds into the reasonable expectation that someone might search + for the name and expect to find it ("what did Rust call `mkdir`"). - There must be an obvious single target for the alias that is an *exact* analogue of the aliased name. We will not add the same alias to multiple declarations. (`const` and non-`const` versions of the same function are From 29d77cd7d8c8bd2c4c7167febd2b5a2f75309fd4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 7 Jul 2021 11:22:33 -0700 Subject: [PATCH 5/5] Fix typo Co-authored-by: Jane Lusby --- src/documentation/doc-alias-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index 0d3dd05..fedfad1 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -13,7 +13,7 @@ cases where we add doc aliases, and the cases where we omit those aliases. names, but that for more general documentation searches they'll turn to a web search engine. - Related: we don't expect that people are currently searching Rust - documentation for language-specific name from arbitrary languages they're + documentation for language-specific names from arbitrary languages they're familiar with, and we don't want to add that as a new documentation search feature; please don't add aliases based on your favorite language. Those mappings should live in separate guides or references. We do expect that