Merge pull request #789 from MicrosoftDocs/main

Merge main to live 6/30/23

Contribute/TOC.yml

@@ -60,16 +60,18 @@
       items:
         - name: How to contribute
           href: dotnet/dotnet-contribute.md
-        - name: Code analysis docs
-          href: dotnet/dotnet-contribute-code-analysis.md
         - name: Labels, projects, and milestones roadmap
           href: dotnet/labels-projects.md
         - name: Style conventions
           href: dotnet/dotnet-style-guide.md
         - name: Voice and tone guide
           href: dotnet/dotnet-voice-tone.md
+        - name: API reference guidelines
+          href: dotnet/api-documentation.md
         - name: Pull request review process
           href: dotnet/dotnet-pr-review.md
+        - name: Code analysis docs
+          href: dotnet/dotnet-contribute-code-analysis.md
         - name: .NET naming in docs
           href: dotnet/net-core-5-naming.md
     - name: Azure Architecture Center

Contribute/docfx.json

@@ -43,10 +43,8 @@
       "hideScope": false,
       "feedback_system": "GitHub",
       "feedback_github_repo": "MicrosoftDocs/Contribute",
-      "feedback_product_url": "https://aka.ms/sitefeedback",
-      "author": "billwagner",
-      "ms.author": "wiwagn",
-      "manager": "wpickett",
+      "author": "carlyrevier",
+      "ms.author": "cahublou",
       "ms.prod": "non-product-specific",
       "ms.topic": "contributor-guide",
       "ms.custom": "external-contributor-guide"

Contribute/dotnet/api-documentation.md

@@ -0,0 +1,121 @@
+---
+title: How to write /// docs for .NET API ref
+ms.date: 06/29/2023
+author: gewarren
+ms.author: gewarren
+ms.prod: non-product-specific
+ms.topic: contributor-guide
+description: Learn how to write good descriptions in source code for generating .NET API reference documentation.
+---
+# How to write good /// docs for .NET API reference
+
+The ultimate goal for .NET API docs is to have the /// XML comments in the .NET source code be the "source of truth". For MSBuild, ASP.NET Core, and EF Core, this goal has been met. However, currently the [dotnet-api-docs repo](https://github.com/dotnet/dotnet-api-docs) remains the source of truth for core .NET API reference. [This dotnet/runtime issue](https://github.com/dotnet/runtime/issues/44969) tracks the effort to backport .NET docs and make the [dotnet/runtime](https://github.com/dotnet/runtime) repo the source of truth.
+
+This article provides tips about writing good doc comments *within the source code itself*.
+
+## Good comments make for good documents
+
+.NET API triple-slash comments are transformed into public documentation on learn.microsoft.com and also appear in IntelliSense in the IDE. The comments should be:
+
+- Complete—empty doc entries for methods, parameters, exceptions, and so on, make the APIs feel under-supported, temporary, or trivial.
+- Correct—readers scan for critical details and become frustrated when key information is missing or incorrect.
+- Contextual—readers land on this page from search and need to know how and when to use the API, and what the code implications are.
+- Polished—poor or hasty grammar and spelling can confuse the reader and make even simple calls ambiguous; also, poor presentation communicates low investment.
+
+## Best practices
+
+1. Use `cref` instead of `href` to link to another type or method.
+
+   Correct: `<param name="configFile">An <see cref="XmlConfigResource" /> object.</param>`
+
+   Incorrect:  `<param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>`
+
+1. When referencing parameters, wrap the parameter name in a `<paramref>` tag, for example, `The offset in <paramref name="source" /> where the range begins.`.
+1. If you have more than one paragraph in the doc comment, separate the paragraphs with `<para>` tags.
+1. Wrap code examples in `<code>` tags within `<example>` tags.
+1. Use `<seealso>` to add links to other APIs in the autogenerated "See Also" section.
+
+## XML doc tags
+
+| Tag | Purpose | Example |
+| - | - | - |
+| `<altmember>` | Adds a "See also" link to the specified API.  | `<altmember cref="System.Console.Out" />` |
+| `<c>` | Formats the specified text as code within a description. | `Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.` |
+| `<code>` | Formats multiple lines as code. | `<code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>` |
+| `<example>` | Adds a code example under the "Example" H2 heading. | `<example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>` |
+| `<exception>` | Describes an exception the API can throw. | `<exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>` |
+| `<include>` | Refer to comments in another file that describe the APIs in your source code. | `<include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />`<br/><br/>[.NET MAUI example](https://github.com/dotnet/maui/blob/a064bf8dd9c74909e989fe007053fc05442a7465/src/Controls/src/Core/Layout/AbsoluteLayout.cs#L9) |
+| `<inheritdoc>` | Inherit XML comments from base classes, interfaces, and similar methods. | `<inheritdoc />` |
+| `<list>` | Creates a bulleted or numbered list. | `<list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>` |
+| `<para>` | Separates paragraphs. | |
+| `<paramref>` | Refers to a method parameter. | `Returns the activity with the specified <paramref name="id" />.` |
+| `<related>` | Adds a "See also" link to the specified article. | `<related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>` |
+| `<see cref>` | Links to another API. | `Describes the behavior that caused a <see cref="Scroll" /> event.` |
+| `<see langword>` | Formats the specified text as code. | `Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.` |
+| `<seealso>` | Adds a "See also" link to the specified API. | `<seealso cref="T:System.Single" />` |
+| `<typeparamref>` | Refers to a type parameter. | `The <typeparamref name="THandler" /> is resolved from a scoped service provider.` |
+
+For more information, see [Recommended XML tags for C#](/dotnet/csharp/language-reference/xmldoc/recommended-tags). The [ECMAXML spec](http://docs.go-mono.com/index.aspx?link=man%3amdoc(5)) also has some helpful guidance.
+
+## Cross references
+
+When you use a `<see cref>` tag to link to another API, there's no need to add a prefix to the type name, such as `T:` for type or `M:` for method. In fact, code analysis [rule CA1200](/dotnet/fundamentals/code-analysis/quality-rules/ca1200) flags code comments that add a prefix to the type name in a `cref` tag.
+
+However, when you want link to the general form of a method that has more than one overload, the C# compiler [doesn't currently support that](https://github.com/dotnet/csharplang/issues/320). The workaround for docs is to prefix the method name with `O:` in source code (or `Overload:` in ECMAXML) and suppress [rule CA1200](/dotnet/fundamentals/code-analysis/quality-rules/ca1200). For example: `<altmember cref="O:System.Diagnostics.Process.Kill" />`.
+
+When the `<see cref>` tag is converted to [ECMAXML](http://docs.go-mono.com/index.aspx?link=man%3amdoc(5)), mdoc replaces the type name with the full DocId of the API, which includes a prefix.
+
+## Descriptions
+
+For authoritative guidelines about describing each symbol type and its various parts, see the [.NET API docs wiki](https://github.com/dotnet/dotnet-api-docs/wiki).
+
+## Empty comments
+
+The well-known placeholder text for empty comments is `To be added.`. The Learn build system recognizes this text and removes it when the ECMAXML is converted into HTML, leaving an empty description.
+
+## Separate code files
+
+If your code example is lengthy, you can put it in a separate file in the docs repo and link to it from source code in the following way:
+
+```csharp
+/// <example>
+/// <format type="text/markdown">
+/// <![CDATA[
+///  [!code-csharp[FieldAware](~/docs/samples/Microsoft.ML.Samples/Dynamic/FactorizationMachine.cs)]
+/// ]]></format>
+/// </example>
+```
+
+## Language attributes
+
+Language attributes on `<code>` tags are optional, but they cause the code to be formatted correctly/prettily. For example:
+
+```csharp
+/// <example>
+/// This sample shows the basic pattern for defining a typed client class.
+///   <code language="csharp">
+///     class ExampleClient
+///     {
+///       private readonly HttpClient _httpClient;
+///       private readonly ILogger _logger;
+///
+///       // Typed clients can use constructor injection to access additional services.
+///       public ExampleClient(HttpClient httpClient, ILogger&lt;ExampleClient&gt; logger)
+///       {
+///         _httpClient = httpClient;
+///         _logger = logger;
+///       }
+///     }
+///   </code>
+/// </example>
+```
+
+## Internal APIs
+
+When documenting an API that's not intended to be used by consumers, use wording similar to the following:
+
+`<summary>This type supports the .NET infrastructure and is not intended to be used directly from your code.</summary>`
+
+## See also
+
+- [ECMAXML format](http://docs.go-mono.com/index.aspx?link=man%3amdoc(5))

Contribute/dotnet/dotnet-contribute.md

@@ -12,16 +12,14 @@ Thank you for your interest in contributing to the .NET documentation!
 
 This document covers the process for contributing to the articles and code samples that are hosted on the [.NET documentation site](/dotnet). Contributions may be as simple as typo corrections or as complex as new articles.
 
-The .NET documentation site is built from multiple repositories:
+The .NET documentation site is built from multiple repositories. These are just some of them:
 
 - [.NET conceptual articles and code snippets](https://github.com/dotnet/docs)
 - [Code samples and snippets](https://github.com/dotnet/samples)
-- [.NET Standard, .NET Core, .NET Framework API reference](https://github.com/dotnet/dotnet-api-docs)
+- [.NET API reference](https://github.com/dotnet/dotnet-api-docs)
 - [.NET Compiler Platform SDK reference](https://github.com/dotnet/roslyn-api-docs)
 - [ML.NET API reference](https://github.com/dotnet/ml-api-docs)
 
-Issues for all these repositories are tracked in the [`dotnet/docs`](https://github.com/dotnet/docs/issues) repository.
-
 ## Guidelines for contributions
 
 We appreciate community contributions to docs. The following list shows some guiding rules to keep in mind when you're contributing to the .NET documentation:
@@ -53,7 +51,7 @@ When you find an issue to work on, add a comment to ask if it's open.
 
 Once you've picked a task to work on, follow the [get started](../get-started-setup-github.md) guide to create a GitHub account and set up your environment.
 
-**Step 2:** Fork the `/dotnet/docs`, `dotnet/samples`, `dotnet/dotnet-api-docs`, `dotnet/roslyn-api-docs`, or `dotnet/ml-api-docs` repos as needed and create a branch for your changes.
+**Step 2:** Fork the `/dotnet/docs` repo (or whichever repo you're contributing to) as needed and create a branch for your changes.
 
 For small changes, see [Quick edits to documentation](../index.md#quick-edits-to-documentation).
 
@@ -71,7 +69,7 @@ For **code snippets**, create a subfolder called **snippets** inside the folder
 
 Code snippets are small, focused examples of code that demonstrate the concepts covered in an article. Larger programs intended for download and exploration should be located in the [dotnet/samples](https://github.com/dotnet/samples) repository. Full samples are covered in the section on [Contributing to samples](#contribute-to-samples).
 
-**Step 4:** Submit a Pull Request (PR) from your branch to the default branch.
+**Step 4:** Submit a pull request (PR) from your branch to the default branch.
 
 > [!IMPORTANT]
 > The [comment automation](../how-to-write-workflows-major.md#review-and-sign-off) functionality is not available on any of the .NET docs repositories at this time. Members of the .NET docs team will review and merge your PR.
@@ -185,7 +183,7 @@ To create a sample:
     }
     ```
 
-You build any .NET Core snippet or sample using the .NET Core CLI, which can be installed with [the .NET Core SDK](https://www.microsoft.com/net/download). To build and run your sample:
+You build any .NET snippet or sample using the .NET CLI, which can be installed with [the .NET SDK](https://www.microsoft.com/net/download). To build and run your sample:
 
 1. Go to the sample folder and build to check for errors:
 
@@ -225,7 +223,7 @@ You build any .NET Core snippet or sample using the .NET Core CLI, which can be
    - The `languages` collection should include only those languages available for your sample.
    - The `products` collection should include only those products relevant to your sample.
 
-Except where noted, all samples build from the command line on any platform supported by .NET Core. There are a few samples that are specific to Visual Studio and require Visual Studio 2017 or later. In addition, some samples show platform specific features and will require a specific platform. Other samples and snippets require the .NET Framework and will run on Windows platforms, and will need the Developer Pack for the target Framework version.
+Except where noted, all samples build from the command line on any platform supported by .NET. There are a few samples that are specific to Visual Studio and require Visual Studio 2017 or later. In addition, some samples show platform specific features and will require a specific platform. Other samples and snippets require the .NET Framework and will run on Windows platforms, and will need the Developer Pack for the target Framework version.
 
 ## The C# interactive experience
 
@@ -248,7 +246,7 @@ The C# interactive experience changes how we work with snippets. Visitors can ru
 > [!NOTE]
 > You might notice that some of the topics are not currently following all the guidelines specified here. We're working towards achieving consistency throughout the site. Check the list of [open issues](https://github.com/dotnet/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22%3Abookmark_tabs%3A+Information+Architecture%22) we're currently tracking for that specific goal.
 
-### Contributing to International content
+### Contributing to non-English content
 
 Contributions for Machine Translated (MT) content are currently not accepted. In an effort to improve the quality of MT content, we've transitioned to a Neural MT engine. We accept and encourage contributions for Human Translated (HT) content, which is used to train the Neural MT engine. So over time, contributions to HT content will improve the quality of both HT and MT. MT topics will have a disclaimer stating that part of the topic may be MT, and the **Edit** button won't be displayed, as editing is disabled.
 

Contribute/dotnet/dotnet-pr-review.md

@@ -35,9 +35,9 @@ The processing used by the Contributor License Agreement (CLA) bot is a good gui
 
 ### Small PRs
 
-The changes in small PRs are reviewed for accuracy and checked using the build on the review site. Because they are small, these PRs do not trigger a review of the entire article. 
+The changes in small PRs are reviewed for accuracy and checked using the build on the review site. Because they are small, these PRs do not trigger a review of the entire article.
 
-Reviewers may notice other small changes that would improve an article. If those changes are also small, suggest them as review comments. If the suggested changes would trigger a larger review, open an issue and address those later. 
+Reviewers may notice other small changes that would improve an article. If those changes are also small, suggest them as review comments. If the suggested changes would trigger a larger review, open an issue and address those later.
 
 ### Larger changes
 
@@ -63,12 +63,12 @@ GitHub lets you enter comments in triple-back-tick blocks of type `suggestion` t
 
 ## Respond to reviews
 
-The author updates the PR to respond to comments and marks each addressed comment with the "+1" reaction to indicate it was addressed. If the author disagrees with the comment, or addresses the comment in a different PR, the author adds a comment explaining their change.
+The author updates the PR to respond to comments. If the author disagrees with the comment, or addresses the comment in a different PR, the author adds a comment explaining their change.
 
-The author @-mentions the original reviewer in a comment to request a new review. 
+The author @-mentions the original reviewer in a comment to request a new review.
 
 ## Response time expectations
 
-Content team members will typically review new PRs in under two business days. If it takes longer to review, one of the team members will add a comment to acknowledge the PR and set expectations.
+Content team members will typically review new PRs in under two business days.
 
 Once a review has been submitted, authors should try to respond to comments in a week or less. Volunteers may not be able to meet these expectations because of other commitments. In those cases, team members ask if the community author will update the PR. If not, the team member updates and merges the PR for them.

Contribute/dotnet/dotnet-style-guide.md

@@ -145,23 +145,7 @@ For information about the Markdown syntax for showing code in docs, see [How to
 
 ## Videos
 
-Currently, you can embed both Channel 9 and YouTube videos with the following syntax:
-
-### Channel 9
-
-```markdown
-> [!VIDEO <channel9_video_link>]
-```
-
-To get the video's correct URL, select the **Embed** tab below the video frame, and copy the URL from the `<iframe>` element. For example:
-
-```markdown
-> [!VIDEO https://channel9.msdn.com/Blogs/dotnet/NET-Core-20-Released/player]
-```
-
-### YouTube
-
-To get the video's correct URL, right-click on the video, select **Copy Embed Code**, and copy the URL from the `<iframe>` element.
+You can embed YouTube videos in a Markdown file. To get the video's correct URL, right-click on the video, select **Copy Embed Code**, and copy the URL from the `<iframe>` element.
 
 ```markdown
 > [!VIDEO <youtube_video_link>]