VSadov/Satori
1
0
Fork 0
mirror of https://github.com/VSadov/Satori.git synced 2025-06-08 03:27:04 +09:00
Code Activity

Add documentation guidelines when adding new APIs (#1335)

Browse source 
* Add documentation guidelines when adding new APIs

* Update docs/coding-guidelines/adding-api-guidelines.md

Co-Authored-By: Dan Moseley <danmose@microsoft.com>

* Update docs/coding-guidelines/adding-api-guidelines.md

Co-Authored-By: Dan Moseley <danmose@microsoft.com>

* Update docs/coding-guidelines/adding-api-guidelines.md

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>

* Update docs/coding-guidelines/adding-api-guidelines.md

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>

* Update docs/coding-guidelines/adding-api-guidelines.md

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>

Co-authored-by: Dan Moseley <danmose@microsoft.com>
Co-authored-by: Maira Wenzel <mairaw@microsoft.com>
This commit is contained in:
Carlos Sanchez Lopez 2020-01-06 13:57:05 -08:00 • committed by Stephen Toub
parent 5afe409d59
commit 3ad3b6fe71
1 changed files with 12 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/coding-guidelines/adding-api-guidelines.md
View file

@ -10,6 +10,7 @@ Recommended reading to better understand this document:
- [Determine target framework](#determine-target-framework)
- [Determine library version](#determine-library-version)
- [Making the changes in repo](#making-the-changes-in-repo)
- [Documentation](#documentation)
- [FAQ](#faq)
### Determine what library
@ -58,6 +59,17 @@ the implementation without compat concerns in future releases.
- Add new test code following [conventions](project-guidelines.md#code-file-naming-conventions) for new files to that are specific to the new target framework.
- To run just the new test configuration run `dotnet msbuild <Library>.csproj /t:RebuildAndTest /p:TargetGroup=<TargetGroup>`
## Documentation
New public APIs must be documented with triple-slash comments on top of them. Visual Studio automatically generates the structure for you when you type `///`.
If your new API or the APIs it calls throw any exceptions, those need to be manually documented by adding the `<exception></exception>` elements.
After your change is merged, we will eventually port them to the dotnet-api-docs repo, where we will review them for language and proper style (For more information, see the [API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki)).
Once the dotnet-api-docs change is merged, your comments will start showing up in the official API documentation at http://docs.microsoft.com/, and later they'll appear in IntelliSense in Visual Studio and Visual Studio Code.
Once the documentation is official, any subsequent updates to it must be made directly in https://github.com/dotnet/dotnet-api-docs/. It's fine to make updates to the triple slash comments later, they just won't automatically flow into the official docs.
## FAQ
_**<a name="isnetstandard">Is your API part of netstandard?</a>**_