-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improved Documentation Readability (#26982)
Updated the project documentation to enhance its readability by correcting grammatical errors, and rephrasing a couple of unclear sentences. These changes aim to make the documentation clearer for all users and contributors.
- Loading branch information
1 parent
5e77ff6
commit 78ca201
Showing
7 changed files
with
51 additions
and
51 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,36 +1,36 @@ | ||
| # Code Documentation Guidelines | ||
|
|
||
| In this document you will find the guidelines for adding XML comments to our codebase. By adding consistent and well-formatted comments to our code we benefit on all fronts: the online API docs are a useful reference for people looking up our APIs, the IntelliSense inside of Visual Studio will help developers understand our product better, and contributors and maintainers of this repository will have all the documentation at hand. | ||
| In this document you will find the guidelines for adding XML comments to our codebase. By adding consistent and well-formatted comments to our code, we benefit on all fronts: the online API docs are a useful reference for people looking up our APIs, the IntelliSense inside of Visual Studio will help developers understand our product better, and contributors and maintainers of this repository will have all the documentation at hand. | ||
|
|
||
| ## Guidelines | ||
|
|
||
| For what kind of comments to our code we mainly follow the [recommended XML tags documentation](https://learn.microsoft.com/dotnet/csharp/language-reference/xmldoc/recommended-tags) by Microsoft. This is also what is best supported by Visual Studio. As a rule of thumb: complete your code first and just start typing a triple slash (`///`) above your code. That will suggest all the attributes that we want to see. Which attributes will show up is inferred from your code. | ||
| For comments on our code, we primarily follow the [recommended XML tags documentation](https://learn.microsoft.com/dotnet/csharp/language-reference/xmldoc/recommended-tags) by Microsoft. These tags are also best supported by Visual Studio. As a rule of thumb, complete your code first and just start typing a triple slash (`///`) above your code. This will suggest all the attributes we expect to see. The attributes that appear are inferred from your code. | ||
|
|
||
| If you're unsure about how to document a certain element, have a look the [.NET API docs wiki](https://github.com/dotnet/dotnet-api-docs/wiki) which has a very extensive description on what kind of comment to add on which element in the code. We would highly recommend going through that and applying the same style of comments everywhere. | ||
| If you're unsure about how to document a certain element, have a look at the [.NET API docs wiki](https://github.com/dotnet/dotnet-api-docs/wiki) which has a very extensive description of what kind of comment to add on which element in the code. We would highly recommend going through that and applying the same style of comments everywhere. | ||
|
|
||
| These are the tags that we would like to see when applicable: `<summary>`, `<remarks>`, `<returns>`, `<param>`, `<exception>`, `<inheritdoc>`, `<see>`, `<c>`. | ||
|
|
||
| * All public members should have at the very least a `<summary>` | ||
| * Add "This is a bindable property." to the end of the summary of the regular C# properties that are bindable properties. | ||
| * Keep the descriptions short and concise | ||
| * 1-2 lines typically, no screenshots or long code-blocks (those belong in the conceptual docs) | ||
| * 1-2 lines typically, no screenshots or long code blocks (those belong in the conceptual docs) | ||
| * Make sure the spelling is correct | ||
| * Add the descriptions at the highest base class/interface level. On an implementing type add `<inheritdoc/>` on each member | ||
| * If the implemented member differs too much you can choose to override the comments; typically this shouldn't be necessary | ||
| * Add the descriptions at the highest base class/interface level. On an implementing type, add `<inheritdoc/>` on each member | ||
| * If the implemented member differs too much, you can choose to override the comments; typically this shouldn't be necessary | ||
| * When adding `<inheritdoc/>` on a class where you want to inherit the comments from an interface, you will have to be explicit about which interface to inherit from. Even if the class only implements one interface. For example: `<inheritdoc cref="IEntry"/>` will inherit the comments from the `IEntry` interface. | ||
| * Do **not** add `<inheritdoc/>` to overridden members, this will potentially cause issues in the online API docs system and doesn't add any value. The documentation is inherited implicitly. | ||
| * Where applicable make references to other types and parameters with the appropriate tags (`<see cref="YourType"/>` and `<paramref name="parameterName"/>` respectively). This will create links in IntelliSense and online API docs | ||
| * Reference all C# keywords with a `<see langword="keyword"/>` tag. For example for `true`: `<see langword="true"/>` | ||
| * If you do want to add a minimal amount of code in your comment, use the `<c></c>` tags which formats it as code | ||
| * Do **not** add `<inheritdoc/>` to overridden members; this will potentially cause issues in the online API docs system and doesn't add any value. The documentation is inherited implicitly. | ||
| * Where applicable, make references to other types and parameters with the appropriate tags (`<see cref="YourType"/>` and `<paramref name="parameterName"/>` respectively). This will create links in IntelliSense and online API docs | ||
| * Reference all C# keywords with a `<see langword="keyword"/>` tag. For example, for `true`: `<see langword="true"/>` | ||
| * If you do want to add a minimal amount of code in your comment, use the `<c></c>` tags, which format it as code | ||
| * Think of things you'd like to know as a developer/future-you maintainer: | ||
| * default values that are not obvious | ||
| * in which scale a value should be (seconds or milliseconds, 0.0 is nothing 1.0 is everything) | ||
| * what exceptions can you expect and what triggers them | ||
| * what exceptions can you expect, and what triggers them? | ||
|
|
||
| If you are looking for examples, browse through the codebase, searching for the `<summary>` tag or `///` should give you all kinds of examples. | ||
| If you are looking for examples, browsing through the codebase, searching for the `<summary>` tag or `///` should give you all kinds of examples. | ||
|
|
||
| ## "Testing" the documentation | ||
|
|
||
| You can "test" the docs by simply hovering over the type in Visual Studio. The IntelliSense updates should be instantaneous when you have edited something. See image below for an example. | ||
| You can "test" the docs by simply hovering over the type in Visual Studio. The IntelliSense updates should be instantaneous when you have edited something. See the image below for an example. | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.