` element wraps the documentation text which follows
42 | it:
43 |
44 | ```csharp
45 | /// Summary text.
46 | ///
47 | /// Remarks text.
48 | /// Second paragraph of remarks, which is now placed inside the <para> element.
49 | ///
50 | public void SomeOperation()
51 | {
52 | }
53 | ```
54 |
55 | ## How to suppress violations
56 |
57 | Do not suppress violations of this rule. If the preferred documentation style does not align with the rule decription,
58 | it is best to disable the rule.
59 |
--------------------------------------------------------------------------------
/docs/DOC200.md:
--------------------------------------------------------------------------------
1 | # DOC200
2 |
3 |
4 |
5 | | TypeName |
6 | DOC200UseXmlDocumentationSyntax |
7 |
8 |
9 | | CheckId |
10 | DOC200 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation for the element contains an HTML element equivalent to a known XML documentation element.
21 |
22 | ## Rule description
23 |
24 | A violation of this rule occurs when an XML documentation comment contains an HTML element instead of the corresponding
25 | XML documentation comment syntax.
26 |
27 | ## How to fix violations
28 |
29 | To fix a violation of this rule, use the expected XML documentation element instead of the HTML element.
30 |
31 | | HTML Element | XML Element |
32 | | --- | --- |
33 | | `` | `` |
34 | | `` | `` |
35 | | `` | `` |
36 | | `` | `` |
37 | | `` | `` |
38 |
39 | ## How to suppress violations
40 |
41 | ```csharp
42 | #pragma warning disable DOC200 // Use XML documentation syntax
43 | ///
44 | /// Summary text with inline code.
45 | ///
46 | public void SomeOperation()
47 | #pragma warning restore DOC200 // Use XML documentation syntax
48 | {
49 | }
50 | ```
51 |
--------------------------------------------------------------------------------
/docs/DOC201.md:
--------------------------------------------------------------------------------
1 | # DOC201
2 |
3 |
4 |
5 | | TypeName |
6 | DOC201ItemShouldHaveDescription |
7 |
8 |
9 | | CheckId |
10 | DOC201 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation for an `- ` within a `
` did not include the required `` and/or ``
21 | elements.
22 |
23 | ## Rule description
24 |
25 | According to the C# language specification, the `- ` element within a documentation comment must have its content
26 | wrapped in a `` element. Not all documentation processing tools support omitting the ``
27 | element, so it should be included for consistent behavior.
28 |
29 | ```csharp
30 | ///
31 | ///
32 | /// - This item has text not wrapped in a description element.
33 | ///
34 | ///
35 | public void SomeOperation()
36 | {
37 | }
38 | ```
39 |
40 | See [dotnet/csharplang#1765](https://github.com/dotnet/csharplang/issues/1765) for a language proposal to natively
41 | support lists with the `` element removed.
42 |
43 | ## How to fix violations
44 |
45 | To fix a violation of this rule, wrap the content of the `- ` element in a `` element.
46 |
47 | ```csharp
48 | ///
49 | ///
50 | /// - This item has text wrapped in a description element.
51 | ///
52 | ///
53 | public void SomeOperation()
54 | {
55 | }
56 | ```
57 |
58 | ## How to suppress violations
59 |
60 | This rule can be disabled rather than suppressed for projects whose documentation processing tools support `- `
61 | elements which are not wrapped in a `` element. In other cases, the warning can be suppressed as follows:
62 |
63 | ```csharp
64 | #pragma warning disable DOC201 // Item should have description
65 | ///
66 | ///
67 | /// - This item has text not wrapped in a description element.
68 | ///
69 | ///
70 | public void SomeOperation()
71 | #pragma warning restore DOC201 // Item should have description
72 | {
73 | }
74 | ```
75 |
--------------------------------------------------------------------------------
/docs/DOC202.md:
--------------------------------------------------------------------------------
1 | # DOC202
2 |
3 |
4 |
5 | | TypeName |
6 | DOC202UseSectionElementsCorrectly |
7 |
8 |
9 | | CheckId |
10 | DOC202 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation contains a section element where a block or inline element was expected.
21 |
22 | ## Rule description
23 |
24 | *TODO*
25 |
26 | ```csharp
27 | ///
28 | /// Summary text.
29 | ///
30 | /// Here is an example:
31 | ///
32 | /// Console.WriteLine();
33 | ///
34 | ///
35 | ///
36 | public void SomeOperation()
37 | {
38 | }
39 | ```
40 |
41 | ## How to fix violations
42 |
43 | To fix a violation of this rule, move the section element outside the block or inline element context, or replace the
44 | section element with an appropriate block or inline element.
45 |
46 | ### Option: Move the section element outside the block element
47 |
48 | ```csharp
49 | ///
50 | /// Summary text.
51 | ///
52 | ///
53 | /// Here is an example:
54 | ///
55 | /// Console.WriteLine();
56 | ///
57 | ///
58 | public void SomeOperation()
59 | {
60 | }
61 | ```
62 |
63 | ### Option: Use an appropriate block element instead of the section element
64 |
65 | ```csharp
66 | ///
67 | /// Summary text.
68 | /// Here is an example:
69 | ///
70 | /// Console.WriteLine();
71 | ///
72 | ///
73 | public void SomeOperation()
74 | {
75 | }
76 | ```
77 |
78 | ## How to suppress violations
79 |
80 | *TODO*
81 |
--------------------------------------------------------------------------------
/docs/DOC203.md:
--------------------------------------------------------------------------------
1 | # DOC203
2 |
3 |
4 |
5 | | TypeName |
6 | DOC203UseBlockElementsCorrectly |
7 |
8 |
9 | | CheckId |
10 | DOC203 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation contains a block element where a section or inline element was expected.
21 |
22 | ## Rule description
23 |
24 | *TODO*
25 |
26 | ## How to fix violations
27 |
28 | To fix a violation of this rule, move the block element inside a section or outside a containing inline element, or
29 | replace the block element with an appropriate section or inline element.
30 |
31 | ## How to suppress violations
32 |
33 | *TODO*
34 |
--------------------------------------------------------------------------------
/docs/DOC204.md:
--------------------------------------------------------------------------------
1 | # DOC204
2 |
3 |
4 |
5 | | TypeName |
6 | DOC204UseInlineElementsCorrectly |
7 |
8 |
9 | | CheckId |
10 | DOC204 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation contains an inline element where a section or block element was expected.
21 |
22 | ## Rule description
23 |
24 | *TODO*
25 |
26 | ## How to fix violations
27 |
28 | *TODO*
29 |
30 | ## How to suppress violations
31 |
32 | *TODO*
33 |
--------------------------------------------------------------------------------
/docs/DOC207.md:
--------------------------------------------------------------------------------
1 | # DOC207
2 |
3 |
4 |
5 | | TypeName |
6 | DOC207UseSeeLangwordCorrectly |
7 |
8 |
9 | | CheckId |
10 | DOC207 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation contains a `` element with an unrecognized keyword.
21 |
22 | ## Rule description
23 |
24 | A violation of this rule occurs when documentation contains a `see langword` element but the reference is not recognized
25 | as a language keyword.
26 |
27 | ```csharp
28 | ///
29 | /// This variable is .
30 | ///
31 | public int correct;
32 | ```
33 |
34 | ## How to fix violations
35 |
36 | To fix a violation of this rule, replace the `see langword` syntax with the equivalent inline code.
37 |
38 | ```csharp
39 | ///
40 | /// This variable is correct.
41 | ///
42 | public int correct;
43 | ```
44 |
45 | ## How to suppress violations
46 |
47 | ```csharp
48 | #pragma warning disable DOC207 // Use 'see langword' correctly
49 | ///
50 | /// This variable is .
51 | ///
52 | public int correct;
53 | #pragma warning restore DOC207 // Use 'see langword' correctly
54 | ```
55 |
--------------------------------------------------------------------------------
/docs/DOC209.md:
--------------------------------------------------------------------------------
1 | # DOC209
2 |
3 |
4 |
5 | | TypeName |
6 | DOC209UseSeeHrefCorrectly |
7 |
8 |
9 | | CheckId |
10 | DOC209 |
11 |
12 |
13 | | Category |
14 | Portability Rules |
15 |
16 |
17 |
18 | ## Cause
19 |
20 | The documentation contains a `` or `` element with an unrecognized URI.
21 |
22 | ## Rule description
23 |
24 | *TODO*
25 |
26 | ## How to fix violations
27 |
28 | *TODO*
29 |
30 | ## How to suppress violations
31 |
32 | *TODO*
33 |
--------------------------------------------------------------------------------
/docs/DOC900.md:
--------------------------------------------------------------------------------
1 | # DOC900
2 |
3 |
4 |
5 | | TypeName |
6 | DOC900RenderAsMarkdown |
7 |
8 |
9 | | CheckId |
10 | DOC900 |
11 |
12 |
13 | | Category |
14 | Refactorings |
15 |
16 |
17 |
18 | ## Description
19 |
20 | This refactoring assists users in converting Markdown syntax within documentation comments to XML syntax recognized by
21 | the compiler and other tools.
22 |
--------------------------------------------------------------------------------
/docs/DOC901.md:
--------------------------------------------------------------------------------
1 | # DOC901
2 |
3 |
4 |
5 | | TypeName |
6 | DOC901ConvertToDocumentationComment |
7 |
8 |
9 | | CheckId |
10 | DOC901 |
11 |
12 |
13 | | Category |
14 | Refactorings |
15 |
16 |
17 |
18 | ## Description
19 |
20 | This refactoring assists users in converting line and block comments preceding a type or member to a documentation
21 | comment for the member.
22 |
--------------------------------------------------------------------------------
/docs/PortabilityRules.md:
--------------------------------------------------------------------------------
1 | ### Portability Rules (DOC200-)
2 |
3 | Rules related to the portability of documentation comments.
4 |
5 | Identifier | Name | Description
6 | -----------|------|-------------
7 | [DOC200](DOC200.md) | UseXmlDocumentationSyntax | The documentation for the element an HTML element equivalent to a known XML documentation element.
8 | [DOC201](DOC201.md) | ItemShouldHaveDescription | The documentation for an `- ` within a `
` did not include the required `` and/or `` elements.
9 | [DOC202](DOC202.md) | UseSectionElementsCorrectly | The documentation contains a section element where a block or inline element was expected.
10 | [DOC203](DOC203.md) | UseBlockElementsCorrectly | The documentation contains a block element where a section or inline element was expected.
11 | [DOC204](DOC204.md) | UseInlineElementsCorrectly | The documentation contains an inline element where a section or block element was expected.
12 | [DOC207](DOC207.md) | UseSeeLangwordCorrectly | The documentation contains a `` element with an unrecognized keyword.
13 | [DOC209](DOC209.md) | UseSeeHrefCorrectly | The documentation contains a `` element with an unrecognized URI.
14 |
--------------------------------------------------------------------------------
/docs/Refactorings.md:
--------------------------------------------------------------------------------
1 | ### Refactorings (DOC900-)
2 |
3 | Additional refactorings provided when the analyzer is installed.
4 |
5 | Identifier | Name | Description
6 | -----------|------|-------------
7 | [DOC900](DOC900.md) | RenderAsMarkdown | Render documentation as Markdown.
8 | [DOC901](DOC901.md) | ConvertToDocumentationComment | Convert a line or block comment to a documentation comment.
9 |
--------------------------------------------------------------------------------
/docs/StyleRules.md:
--------------------------------------------------------------------------------
1 | ### Style Rules (DOC100-)
2 |
3 | Rules related to the style of documentation comments.
4 |
5 | Identifier | Name | Description
6 | -----------|------|-------------
7 | [DOC100](DOC100.md) | PlaceTextInParagraphs | A `` or `` documentation element contains content which is not wrapped in a block-level element.
8 | [DOC101](DOC101.md) | UseChildBlocksConsistently | The documentation for the element contains some text which is wrapped in block-level elements, and other text which is written inline.
9 | [DOC102](DOC102.md) | UseChildBlocksConsistentlyAcrossElementsOfTheSameKind | The documentation for the element contains inline text, but the documentation for a sibling element of the same kind uses block-level elements.
10 | [DOC103](DOC103.md) | UseUnicodeCharacters | The documentation contains an unnecessary or unrecognized HTML character entity.
11 | [DOC104](DOC104.md) | UseSeeLangword | The documentation contains a language keyword reference using `keyword` that can be converted to the preferred form ``.
12 | [DOC105](DOC105.md) | UseParamref | The documentation contains a parameter reference using `name` that can be converted to the preferred form ``.
13 | [DOC106](DOC106.md) | UseTypeparamref | The documentation contains a type parameter reference using `T` that can be converted to the preferred form ``.
14 | [DOC107](DOC107.md) | UseSeeCref | The documentation contains a code element reference using `name` that can be converted to the preferred form ``.
15 | [DOC108](DOC108.md) | AvoidEmptyParagraphs | The documentation contains an empty paragraph element (`` or ``) used as a paragraph separator.
16 |
--------------------------------------------------------------------------------