From c17f60cd2ad9b830687b39d0e4fba7e8f99d9877 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 10 Sep 2024 14:25:42 -0400 Subject: [PATCH 1/8] Explain how to name rule identifiers --- docs/authoring.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/authoring.md b/docs/authoring.md index 74c9bc962..5fbbbe966 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -75,6 +75,36 @@ Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are In the HTML, the rules are clickable just like headers. +When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: +1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to, +2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break +3. Rust Code examples and tests do not need their own rules +4. Notes do not need rules. For other admonition types, use the following guidelines: + * Warning: Omit the rule if and only if the warning follows from the previous paragraph. + * Target Specific Behaviour: Always include the rule + * Edition Differences: Always include the rule + * Version History: Omit the rule if the present behaviour is explained in the immediately preceeding rule. +4. The following keywords should be used to identify paragraphs when unambiguous: + * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. + * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used + * `restriction`: Syntactic (parsing) requirements on the construct + * `constraint`: Semantic (type checking) requirements on the construct + * `safety` (instead of restriction): Stating that an operation is `unsafe` or the conditions under which it is `unsafe` + * `behavior`: Runtime effects of evaluating the construct in a well-defined manner + * `panics`: Conditions under which evaluating the construct causes a runtime panic + * `preconditions`: Conditions which must be satisfied for the evaluation of the construct to be well-defined + * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`) +5. When a rule doesn't fall under the above keywords. or for section rule ids, name the subrule as follows: + * If the rule is naming a specific Rust language construct (IE. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s) + * Other than rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule" + * Whenever possible, do not repeat previous components of the rule + * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]) + * Whenever possible, don't use a name that conflicts with one of the above keywords, even if this violates the first bullet. + * Use an appropriately discriptive, but short, name if the language does not provide one. +6. When a keyword applies, but multiple different rules in the same section would use the same keyword, prefix or suffix the rule with a descriptive id given above, separated with a `-` + * When the paragraph modifies a specific named construct or applies to a specific named construct only, prefix the rule with the name of the construct (e.g. `r[items.fn.params.self-constraint]`). + * When the paragraph refers to a specific named construct that applies the particular keyword behaviour, suffix the rule with the name of the construct + ### Standard library links You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: From 06c1d984297fa803dc767836e4e7315f38e96d09 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 18 Sep 2024 21:55:47 -0400 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Travis Cross --- docs/authoring.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index 5fbbbe966..d64fb211a 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -78,12 +78,12 @@ In the HTML, the rules are clickable just like headers. When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: 1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to, 2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break -3. Rust Code examples and tests do not need their own rules +3. Rust code examples and tests do not need their own rules 4. Notes do not need rules. For other admonition types, use the following guidelines: * Warning: Omit the rule if and only if the warning follows from the previous paragraph. - * Target Specific Behaviour: Always include the rule - * Edition Differences: Always include the rule - * Version History: Omit the rule if the present behaviour is explained in the immediately preceeding rule. + * Target specific behaviour: Always include the rule + * Edition differences: Always include the rule + * Version history: Omit the rule if the present behaviour is explained in the immediately preceeding rule. 4. The following keywords should be used to identify paragraphs when unambiguous: * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used @@ -95,7 +95,7 @@ When assigning rules to new paragraphs, or when modifying rule names, use the fo * `preconditions`: Conditions which must be satisfied for the evaluation of the construct to be well-defined * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`) 5. When a rule doesn't fall under the above keywords. or for section rule ids, name the subrule as follows: - * If the rule is naming a specific Rust language construct (IE. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s) + * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s) * Other than rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule" * Whenever possible, do not repeat previous components of the rule * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]) From 8912726a0d3ed876bdb0f7eee7cae532dc6fbdbf Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Mon, 23 Sep 2024 10:57:38 -0400 Subject: [PATCH 3/8] Remove restriction and constraint keywords --- docs/authoring.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index d64fb211a..975ab7800 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -87,8 +87,6 @@ When assigning rules to new paragraphs, or when modifying rule names, use the fo 4. The following keywords should be used to identify paragraphs when unambiguous: * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used - * `restriction`: Syntactic (parsing) requirements on the construct - * `constraint`: Semantic (type checking) requirements on the construct * `safety` (instead of restriction): Stating that an operation is `unsafe` or the conditions under which it is `unsafe` * `behavior`: Runtime effects of evaluating the construct in a well-defined manner * `panics`: Conditions under which evaluating the construct causes a runtime panic From d62842583fd4dd2243f784bb48a764f9c773dc35 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Thu, 26 Sep 2024 10:31:34 -0400 Subject: [PATCH 4/8] Apply requested changes from T-lang/docs --- docs/authoring.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index 975ab7800..b61be9394 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -78,19 +78,16 @@ In the HTML, the rules are clickable just like headers. When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: 1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to, 2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break + * This content will be moved to `[!NOTE]` or more specific admonitions in the future. 3. Rust code examples and tests do not need their own rules 4. Notes do not need rules. For other admonition types, use the following guidelines: - * Warning: Omit the rule if and only if the warning follows from the previous paragraph. + * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. * Target specific behaviour: Always include the rule * Edition differences: Always include the rule * Version history: Omit the rule if the present behaviour is explained in the immediately preceeding rule. 4. The following keywords should be used to identify paragraphs when unambiguous: * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used - * `safety` (instead of restriction): Stating that an operation is `unsafe` or the conditions under which it is `unsafe` - * `behavior`: Runtime effects of evaluating the construct in a well-defined manner - * `panics`: Conditions under which evaluating the construct causes a runtime panic - * `preconditions`: Conditions which must be satisfied for the evaluation of the construct to be well-defined * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`) 5. When a rule doesn't fall under the above keywords. or for section rule ids, name the subrule as follows: * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s) @@ -99,9 +96,6 @@ When assigning rules to new paragraphs, or when modifying rule names, use the fo * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]) * Whenever possible, don't use a name that conflicts with one of the above keywords, even if this violates the first bullet. * Use an appropriately discriptive, but short, name if the language does not provide one. -6. When a keyword applies, but multiple different rules in the same section would use the same keyword, prefix or suffix the rule with a descriptive id given above, separated with a `-` - * When the paragraph modifies a specific named construct or applies to a specific named construct only, prefix the rule with the name of the construct (e.g. `r[items.fn.params.self-constraint]`). - * When the paragraph refers to a specific named construct that applies the particular keyword behaviour, suffix the rule with the name of the construct ### Standard library links From d032fa863940c84ff380dc8b590886ad833e4708 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Thu, 26 Sep 2024 10:35:59 -0400 Subject: [PATCH 5/8] Document naming conventions for admonition identifiers --- docs/authoring.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/authoring.md b/docs/authoring.md index b61be9394..3fe66cece 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -94,8 +94,10 @@ When assigning rules to new paragraphs, or when modifying rule names, use the fo * Other than rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule" * Whenever possible, do not repeat previous components of the rule * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]) - * Whenever possible, don't use a name that conflicts with one of the above keywords, even if this violates the first bullet. + * Edition differences admonitions should typically be named by the edition referenced directly by the rule. If multiple editions are named, use the one for which the behaviour is defined by the admonition, and not by a previous paragraph + * Target Specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 cpus, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF os) * Use an appropriately discriptive, but short, name if the language does not provide one. + ### Standard library links From d78728d1517f76f07af03de6fefcfdc3cb075af4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 3 Oct 2024 08:58:58 -0700 Subject: [PATCH 6/8] Fix typos and formatting. --- docs/authoring.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index 3fe66cece..98068948e 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -76,28 +76,29 @@ Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are In the HTML, the rules are clickable just like headers. When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: -1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to, -2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break + +1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to. +2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break. * This content will be moved to `[!NOTE]` or more specific admonitions in the future. -3. Rust code examples and tests do not need their own rules -4. Notes do not need rules. For other admonition types, use the following guidelines: +3. Rust code examples and tests do not need their own rules. +4. Use the following guidelines for admonitions: + * Notes: Do not include a rule. * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. - * Target specific behaviour: Always include the rule - * Edition differences: Always include the rule - * Version history: Omit the rule if the present behaviour is explained in the immediately preceeding rule. -4. The following keywords should be used to identify paragraphs when unambiguous: + * Target specific behavior: Always include the rule. + * Edition differences: Always include the rule. + * Version history: Omit the rule if the present behavior is explained in the immediately preceding rule. +5. The following keywords should be used to identify paragraphs when unambiguous: * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. - * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used - * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`) -5. When a rule doesn't fall under the above keywords. or for section rule ids, name the subrule as follows: - * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s) - * Other than rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule" - * Whenever possible, do not repeat previous components of the rule - * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]) - * Edition differences admonitions should typically be named by the edition referenced directly by the rule. If multiple editions are named, use the one for which the behaviour is defined by the admonition, and not by a previous paragraph - * Target Specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 cpus, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF os) - * Use an appropriately discriptive, but short, name if the language does not provide one. - + * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. + * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). +6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows: + * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). + * Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". + * Whenever possible, do not repeat previous components of the rule. + * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]). + * Edition differences admonitions should typically be named by the edition referenced directly by the rule. If multiple editions are named, use the one for which the behavior is defined by the admonition, and not by a previous paragraph. + * Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). + * Use an appropriately descriptive, but short, name if the language does not provide one. ### Standard library links From 3c7523f51f07b9079c79f9e9ecc2b783e89b3027 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 3 Oct 2024 08:59:47 -0700 Subject: [PATCH 7/8] Remove "version history" We have not specifically decided on including version information, or how it will be done. --- docs/authoring.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/authoring.md b/docs/authoring.md index 98068948e..158ae82b4 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -86,7 +86,6 @@ When assigning rules to new paragraphs, or when modifying rule names, use the fo * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. * Target specific behavior: Always include the rule. * Edition differences: Always include the rule. - * Version history: Omit the rule if the present behavior is explained in the immediately preceding rule. 5. The following keywords should be used to identify paragraphs when unambiguous: * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. From 0ab21815824ec3787f022db3002378c2c6817a02 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 3 Oct 2024 09:03:34 -0700 Subject: [PATCH 8/8] Remove "singular forms" We don't agree on this particular point, as we have been using plurals almost everywhere. There are also some subtle complexities with what the specific guidelines might be. --- docs/authoring.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/authoring.md b/docs/authoring.md index 158ae82b4..1495bc223 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -94,7 +94,6 @@ When assigning rules to new paragraphs, or when modifying rule names, use the fo * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). * Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". * Whenever possible, do not repeat previous components of the rule. - * Prefer using singular forms of words over plural unless the rule applies to a list or the construct is named as plural in the language (e.g. `r[attribute.diagnostic.lint.group]). * Edition differences admonitions should typically be named by the edition referenced directly by the rule. If multiple editions are named, use the one for which the behavior is defined by the admonition, and not by a previous paragraph. * Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). * Use an appropriately descriptive, but short, name if the language does not provide one.