diff --git a/.gitignore b/.gitignore index ab6a5d18654f2..0cc62dc3e033c 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,4 @@ ehthumbs_vista.db # Ionide folder, used in F# for VSCode .ionide/ docs/core/extensions/snippets/workers/cloud-service/Properties/PublishProfiles/cloudworker.pubxml +docs/csharp/language-reference/xmldoc/snippets/xmldoc/xmldoc.xml diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 2e0dad03ca788..7d5869b932f68 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -943,6 +943,10 @@ "source_path": "docs/csharp/csharp.md", "redirect_url": "/dotnet/csharp" }, + { + "source_path": "docs/csharp/codedoc.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, { "source_path": "docs/csharp/deconstruct.md", "redirect_url": "/dotnet/csharp/fundamentals/functional/deconstruct" @@ -3240,6 +3244,110 @@ "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/pointer-types.md", "redirect_url": "/dotnet/csharp/language-reference/unsafe-code#pointer-types" }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/code.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/code-inline.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/cref-attribute.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md", + "redirect_url": "/dotnet/csharp/programming-guide/xmldoc" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/example.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/exception.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md", + "redirect_url": "/dotnet/csharp/programming-guide/xmldoc/index" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/include.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/index.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/inheritdoc.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/list.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/para.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/param.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/paramref.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/permission.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/index" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc#id-strings" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/remarks.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/returns.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/see.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/seealso.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/summary.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/typeparam.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/typeparamref.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, + { + "source_path": "docs/csharp/programming-guide/xmldoc/value.md", + "redirect_url": "/dotnet/csharp/language-reference/xmldoc/recommended-tags" + }, { "source_path": "docs/csharp/programming-guide/xmldoc/xml-documentation-comments.md", "redirect_url": "/dotnet/csharp/programming-guide/xmldoc" diff --git a/docs/csharp/codedoc.md b/docs/csharp/codedoc.md deleted file mode 100644 index 9bcc9dcce06c7..0000000000000 --- a/docs/csharp/codedoc.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Document your C# code with XML comments -description: Learn how to document your code with XML documentation comments and generate an XML documentation file at compile time. -ms.date: 01/21/2020 -ms.technology: csharp-fundamentals -ms.assetid: 8e75e317-4a55-45f2-a866-e76124171838 ---- -# Document your C# code with XML comments - -XML documentation comments are a special kind of comment, added above the definition of any user-defined type or member. -They are special because they can be processed by the compiler to generate an XML documentation file at compile time. -The compiler-generated XML file can be distributed alongside your .NET assembly so that Visual Studio and other IDEs can use IntelliSense to show quick information about types or members. Additionally, the XML file can be run through tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to generate API reference websites. - -XML documentation comments, like all other comments, are ignored by the compiler. - -You can generate the XML file at compile time by doing one of the following: - -- If you are developing an application with .NET Core from the command line, you can add a `GenerateDocumentationFile` element to the `` section of your .csproj project file. You can also specify the path to the documentation file directly using [`DocumentationFile` element](/visualstudio/msbuild/common-msbuild-project-properties). The following example generates an XML file in the project directory with the same root filename as the assembly: - - ```xml - true - ``` - - This is equivalent to the following: - - ```xml - bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml - ``` - -- If you are developing an application using Visual Studio, right-click on the project and select **Properties**. In the properties dialog, select the **Build** tab, and check **XML documentation file**. You can also change the location to which the compiler writes the file. - -- If you are compiling a .NET application from the command line, add the [**DocumentationFile** compiler option](language-reference/compiler-options/output.md#documentationfile) when compiling. - -XML documentation comments use triple forward slashes (`///`) and an XML formatted comment body. For example: - -[!code-csharp[XML Documentation Comment](../../samples/snippets/csharp/concepts/codedoc/xml-comment.cs)] - -## Walkthrough - -Let's walk through documenting a very basic math library to make it easy for new developers to understand/contribute and for third-party developers to use. - -Here's code for the simple math library: - -[!code-csharp[Sample Library](../../samples/snippets/csharp/concepts/codedoc/sample-library.cs)] - -The sample library supports four major arithmetic operations (`add`, `subtract`, `multiply`, and `divide`) on `int` and `double` data types. - -Now you want to be able to create an API reference document from your code for third-party developers who use your library but don't have access to the source code. -As mentioned earlier XML documentation tags can be used to achieve this. You will now be introduced to the standard XML tags the C# compiler supports. - -## \ - -The `` tag adds brief information about a type or member. -I'll demonstrate its use by adding it to the `Math` class definition and the first `Add` method. Feel free to apply it to the rest of your code. - -[!code-csharp[Summary Tag](~/samples/snippets/csharp/concepts/codedoc/summary-tag.cs)] - -The `` tag is important, and we recommend that you include it because its content is the primary source of type or member information in IntelliSense or an API reference document. - -## \ - -The `` tag supplements the information about types or members that the `` tag provides. In this example, you'll just add it to the class. - -[!code-csharp[Remarks Tag](~/samples/snippets/csharp/concepts/codedoc/remarks-tag.cs)] - -## \ - -The `` tag describes the return value of a method declaration. -As before, the following example illustrates the `` tag on the first `Add` method. You can do the same on other methods. - -[!code-csharp[Returns Tag](~/samples/snippets/csharp/concepts/codedoc/returns-tag.cs)] - -## \ - -The `` tag is similar to the `` tag, except that you use it for properties. -Assuming your `Math` library had a static property called `PI`, here's how you'd use this tag: - -[!code-csharp[Value Tag](~/samples/snippets/csharp/concepts/codedoc/value-tag.cs)] - -## \ - -You use the `` tag to include an example in your XML documentation. -This involves using the child `` tag. - -[!code-csharp[Example Tag](~/samples/snippets/csharp/concepts/codedoc/example-tag.cs)] - -The `code` tag preserves line breaks and indentation for longer examples. - -## \ - -You use the `` tag to format the content within its parent tag. `` is usually used inside a tag, such as `` or ``, to divide text into paragraphs. -You can format the contents of the `` tag for your class definition. - -[!code-csharp[Para Tag](~/samples/snippets/csharp/concepts/codedoc/para-tag.cs)] - -## \ - -Still on the topic of formatting, you use the `` tag for marking part of text as code. -It's like the `` tag but inline. It's useful when you want to show a quick code example as part of a tag's content. -Let's update the documentation for the `Math` class. - -[!code-csharp[C Tag](~/samples/snippets/csharp/concepts/codedoc/c-tag.cs)] - -## \ - -By using the `` tag, you let your developers know that a method can throw specific exceptions. -Looking at your `Math` library, you can see that both `Add` methods throw an exception if a certain condition is met. Not so obvious, though, -is that integer `Divide` method throws as well if the `b` parameter is zero. Now add exception documentation to this method. - -[!code-csharp[Exception Tag](~/samples/snippets/csharp/concepts/codedoc/exception-tag.cs)] - -The `cref` attribute represents a reference to an exception that is available from the current compilation environment. -This can be any type defined in the project or a referenced assembly. The compiler will issue a warning if its value cannot be resolved. - -## \ - -The `` tag lets you create a clickable link to a documentation page for another code element. In our next example, we'll create a clickable link between the two `Add` methods. - -[!code-csharp[See Tag](~/samples/snippets/csharp/concepts/codedoc/see-tag.cs)] - -The `cref` is a **required** attribute that represents a reference to a type or its member that is available from the current compilation environment. -This can be any type defined in the project or a referenced assembly. - -## \ - -You use the `` tag in the same way you do the `` tag. The only difference is that its content is typically placed in a "See Also" section. Here we'll add a `seealso` tag on the integer `Add` method to reference other methods in the class that accept integer parameters: - -[!code-csharp[Seealso Tag](~/samples/snippets/csharp/concepts/codedoc/seealso-tag.cs)] - -The `cref` attribute represents a reference to a type or its member that is available from the current compilation environment. -This can be any type defined in the project or a referenced assembly. - -## \ - -You use the `` tag to describe a method's parameters. Here's an example on the double `Add` method: -The parameter the tag describes is specified in the **required** `name` attribute. - -[!code-csharp[Param Tag](~/samples/snippets/csharp/concepts/codedoc/param-tag.cs)] - -## \ - -You use `` tag just like the `` tag but for generic type or method declarations to describe a generic parameter. -Add a quick generic method to your `Math` class to check if one quantity is greater than another. - -[!code-csharp[Typeparam Tag](~/samples/snippets/csharp/concepts/codedoc/typeparam-tag.cs)] - -## \ - -Sometimes you might be in the middle of describing what a method does in what could be a `` tag, and you might want to make a reference to a parameter. The `` tag is great for just this. Let's update the summary of our double based `Add` method. Like the `` tag, the parameter name is specified in the **required** `name` attribute. - -[!code-csharp[Paramref Tag](~/samples/snippets/csharp/concepts/codedoc/paramref-tag.cs)] - -## \ - -You use `` tag just like the `` tag but for generic type or method declarations to describe a generic parameter. -You can use the same generic method you previously created. - -[!code-csharp[Typeparamref Tag](~/samples/snippets/csharp/concepts/codedoc/typeparamref-tag.cs)] - -## \ - -You use the `` tag to format documentation information as an ordered list, unordered list, or table. Make an unordered list of every math operation your `Math` library supports. - -[!code-csharp[List Tag](~/samples/snippets/csharp/concepts/codedoc/list-tag.cs)] - -You can make an ordered list or table by changing the `type` attribute to `number` or `table`, respectively. - -## \ - -You can use the `` tag to inherit XML comments from base classes, interfaces, and similar methods. This eliminates unwanted copying and pasting of duplicate XML comments and automatically keeps XML comments synchronized. - -[!code-csharp-interactive[InheritDoc Tag](~/samples/snippets/csharp/concepts/codedoc/inheritdoc-tag.cs)] - -### Put it all together - -If you've followed this tutorial and applied the tags to your code where necessary, your code should now look similar to the following: - -[!code-csharp[Tagged Library](~/samples/snippets/csharp/concepts/codedoc/tagged-library.cs)] - -From your code, you can generate a detailed documentation website complete with clickable cross-references. But you're faced with another problem: your code has become hard to read. -There's so much information to sift through that this is going to be a nightmare for any developer who wants to contribute to this code. -Thankfully there's an XML tag that can help you deal with this: - -## \ - -The `` tag lets you refer to comments in a separate XML file that describe the types and members in your source code, as opposed to placing documentation comments directly in your source code file. - -Now you're going to move all your XML tags into a separate XML file named `docs.xml`. Feel free to name the file whatever you want. - -[!code-xml[Sample XML](~/samples/snippets/csharp/concepts/codedoc/include.xml)] - -In the above XML, each member's documentation comments appear directly inside a tag named after what they do. You can choose your own strategy. -Now that you have your XML comments in a separate file, let's see how your code can be made more readable by using the `` tag: - -[!code-csharp[Include Tag](~/samples/snippets/csharp/concepts/codedoc/include-tag.cs)] - -And there you have it: our code is back to being readable, and no documentation information has been lost. - -The `file` attribute represents the name of the XML file containing the documentation. - -The `path` attribute represents an [XPath](../standard/data/xml/xpath-queries-and-namespaces.md) query to the `tag name` present in the specified `file`. - -The `name` attribute represents the name specifier in the tag that precedes the comments. - -The `id` attribute, which can be used in place of `name`, represents the ID for the tag that precedes the comments. - -### User-defined tags - -All the tags outlined above represent those that are recognized by the C# compiler. However, a user is free to define their own tags. -Tools like Sandcastle bring support for extra tags like [\](https://ewsoftware.github.io/XMLCommentsGuide/html/81bf7ad3-45dc-452f-90d5-87ce2494a182.htm) and [\](https://ewsoftware.github.io/XMLCommentsGuide/html/4302a60f-e4f4-4b8d-a451-5f453c4ebd46.htm), -and even support [documenting namespaces](https://ewsoftware.github.io/XMLCommentsGuide/html/BD91FAD4-188D-4697-A654-7C07FD47EF31.htm). -Custom or in-house documentation generation tools can also be used with the standard tags and multiple output formats from HTML to PDF can be supported. - -## Recommendations - -Documenting code is recommended for many reasons. What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your C# code. - -- For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all. -- Private members can also be documented using XML comments. However, this exposes the inner (potentially confidential) workings of your library. -- At a bare minimum, types and their members should have a `` tag because its content is needed for IntelliSense. -- Documentation text should be written using complete sentences ending with full stops. -- Partial classes are fully supported, and documentation information will be concatenated into a single entry for that type. -- The compiler verifies the syntax of the ``, ``, ``, ``, ``, and `` tags. -- The compiler validates the parameters that contain file paths and references to other parts of the code. - -## See also - -- [XML Documentation Comments (C# Programming Guide)](programming-guide/xmldoc/index.md) -- [Recommended Tags for Documentation Comments (C# Programming Guide)](programming-guide/xmldoc/recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/how-to/index.md b/docs/csharp/how-to/index.md index 6e05162950cc5..db403150d1933 100644 --- a/docs/csharp/how-to/index.md +++ b/docs/csharp/how-to/index.md @@ -29,7 +29,7 @@ You create classes, records, and structs to implement your program. These techni - [Define constants](../programming-guide/classes-and-structs/how-to-define-constants.md). - [Override the `ToString` method to provide string output](../programming-guide/classes-and-structs/how-to-override-the-tostring-method.md). - [Define abstract properties](../programming-guide/classes-and-structs/how-to-define-abstract-properties.md). -- [Use the xml documentation features to document your code](../programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md). +- [Use the xml documentation features to document your code](../language-reference/xmldoc/index.md). - [Explicitly implement interface members](../programming-guide/interfaces/how-to-explicitly-implement-interface-members.md) to keep your public interface concise. - [Explicitly implement members of two interfaces](../programming-guide/interfaces/how-to-explicitly-implement-members-of-two-interfaces.md). diff --git a/docs/csharp/language-reference/compiler-options/output.md b/docs/csharp/language-reference/compiler-options/output.md index 0b8e8e7282e94..706a4eea6cf1f 100644 --- a/docs/csharp/language-reference/compiler-options/output.md +++ b/docs/csharp/language-reference/compiler-options/output.md @@ -23,13 +23,13 @@ The following options control compiler output generation. The new MSBuild syntax ## DocumentationFile -The **DocumentationFile** option allows you to place documentation comments in an XML file. To learn more about documenting your code, see [Recommended Tags for Documentation Comments](../../programming-guide/xmldoc/recommended-tags-for-documentation-comments.md). The value specifies the path to the output XML file. The XML file contains the comments in the source code files of the compilation. +The **DocumentationFile** option allows you to place documentation comments in an XML file. To learn more about documenting your code, see [Recommended Tags for Documentation Comments](../xmldoc/recommended-tags.md). The value specifies the path to the output XML file. The XML file contains the comments in the source code files of the compilation. ```xml path/to/file.xml ``` -The source code file that contains Main or top-level statements is output first into the XML. You'll often want to use the generated .xml file with [IntelliSense](/visualstudio/ide/using-intellisense). The *.xml* filename must be the same as the assembly name. The *.xml* file must be in the same directory as the assembly. When the assembly is referenced in a Visual Studio project, the *.xml* file is found as well. For more information about generating code comments, see [Supplying Code Comments](/visualstudio/ide/reference/generate-xml-documentation-comments). Unless you compile with [``](#targettype), `file` will contain `` and `` tags specifying the name of the file containing the assembly manifest for the output file. For examples, see [How to use the XML documentation features](../../programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md). +The source code file that contains Main or top-level statements is output first into the XML. You'll often want to use the generated .xml file with [IntelliSense](/visualstudio/ide/using-intellisense). The *.xml* filename must be the same as the assembly name. The *.xml* file must be in the same directory as the assembly. When the assembly is referenced in a Visual Studio project, the *.xml* file is found as well. For more information about generating code comments, see [Supplying Code Comments](/visualstudio/ide/reference/generate-xml-documentation-comments). Unless you compile with [``](#targettype), `file` will contain `` and `` tags specifying the name of the file containing the assembly manifest for the output file. For examples, see [How to use the XML documentation features](../xmldoc/index.md). > [!NOTE] > The **DocumentationFile** option applies to all files in the project. To disable warnings related to documentation comments for a specific file or section of code, use [#pragma warning](../preprocessor-directives.md#pragma-warning). diff --git a/docs/csharp/language-reference/xmldoc/examples.md b/docs/csharp/language-reference/xmldoc/examples.md new file mode 100644 index 0000000000000..d931d13ffe5d6 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/examples.md @@ -0,0 +1,55 @@ +--- +title: "Example XML documentation comments" +description: See documentation examples on many different C# language elements. Learn which tags to use in different situations and for different language elements. +ms.date: 07/14/2021 +ms.topic: how-to +--- +# Example XML documentation comments + +This article contains three examples for adding XML documentation comments to most C# language elements. The first example shows how you document a class with different members. The second shows how you would reuse explanations for a hierarchy of classes or interfaces. The third shows tags to use for generic classes and members. The second and third examples use concepts that are covered in the first example. + +## Document a class, struct, or interface + +The following example shows common language elements, and the tags you'll likely use to describe these elements. The documentation comments describe the use of the tags, rather than the class itself. + +:::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="ClassExample"::: + +Adding documentation can clutter your source code with large sets of comments intended for users of your library. You use the `` tag to separate your XML comments from your source. Your source code references an XML file with the `` tag: + +:::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="IncludeTag"::: + +The second file, *xml_include_tag.xml*, contains the documentation comments. + +:::code language="xml" source="./snippets/xmldoc/xml_include_tag.xml" ::: + +## Document a hierarchy of classes and interfaces + +The `` element means a type or member *inherits* documentation comments from a base class or interface. You can also use the `` element with the `cref` attribute to inherit comments from a member of the same type. The following example shows ways to use this tag. Note that when you add the `inheritdoc` attribute to a type, member comments are inherited. You can prevent the use of inherited comments by writing comments on the members in the derived type. Those will be chosen over the inherited comments. + +:::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="InheritDocTag"::: + +## Generic types + +Use the `` tag to describe type parameters on generic types and methods. The value for the `cref` attribute requires new syntax to reference a generic method or class: + +:::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="GenericExample"::: + +## Math class example + +The following code shows a realistic example of adding doc comments to a math library. + +:::code language="csharp" source="./snippets/xmldoc/tagged-library.cs"::: + +You may find that the code is obscured by all the comments. The final example shows how you would adapt this library to use the `include` tag. You move all the documentation to an XML file: + +:::code language="xml" source="./snippets/xmldoc/include.xml"::: + +In the above XML, each member's documentation comments appear directly inside a tag named after what they do. You can choose your own strategy. +The code uses the `` tag to reference the appropriate element in the XML file: + +:::code language="csharp" source="./snippets/xmldoc/include-tag.cs"::: + +- The `file` attribute represents the name of the XML file containing the documentation. +- The `path` attribute represents an [XPath](../../../standard/data/xml/xpath-queries-and-namespaces.md) query to the `tag name` present in the specified `file`. +- The `name` attribute represents the name specifier in the tag that precedes the comments. +- The `id` attribute, which can be used in place of `name`, represents the ID for the tag that precedes the comments. diff --git a/docs/csharp/language-reference/xmldoc/index.md b/docs/csharp/language-reference/xmldoc/index.md new file mode 100644 index 0000000000000..df0ad1e2a69c2 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/index.md @@ -0,0 +1,163 @@ +--- +title: "XML documentation comments - document APIs using /// comments" +description: Learn about XML documentation comments. You can create documentation for your code by including XML elements in special comment fields. You can use other tools to build documentation layouts from comments. +ms.date: 06/17/2021 +f1_keywords: + - "cs.xml" +helpviewer_keywords: + - "XML [C#], code comments" + - "comments [C#], XML" + - "documentation comments [C#]" + - "C# source code files" + - "C# language, XML code comments" + - "XML documentation comments [C#]" +ms.assetid: 803b7f7b-7428-4725-b5db-9a6cff273199 +--- +# XML documentation comments + +C# source files can have structured comments that produce API documentation for the types defined in those files. The C# compiler produces an *XML* file that contains structured data representing the comments and the API signatures. Other tools can process that XML output to create human-readable documentation in the form of web pages or PDF files, for example. + +This process provides many advantages for you to add API documentation in your code: + +- The C# compiler combines the structure of the C# code with the text of the comments into a single XML document. +- The C# compiler verifies that the comments match the API signatures for relevant tags. +- Tools that process the XML documentation files can define XML elements and attributes specific to those tools. + +Tools like Visual Studio provide IntelliSense for many common XML elements used in documentation comments. + +This article covers these topics: + +- Documentation comments and XML file generation +- Tags validated by the C# compiler and Visual Studio +- Format of the generated XML file + +## Create XML documentation output + +You create documentation for your code by writing special comment fields indicated by triple slashes. The comment fields include XML elements that describe the code block that follows the comments. For example: + +```csharp +/// +/// This class performs an important function. +/// +public class MyClass {} +``` + +You set the [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) option and the compiler will find all comment fields with XML tags in the source code and create an XML documentation file from those comments. When this option is enabled, the compiler generates the [CS1591](../compiler-messages/cs1591.md) warning for any publicly visible member declared in your project without XML documentation comments. + +## XML comment formats + +The use of XML doc comments requires delimiters that indicate where a documentation comment begins and ends. You use the following delimiters with the XML documentation tags: + +- `///` Single-line delimiter: The documentation examples and C# project templates use this form. If there's white space following the delimiter, it isn't included in the XML output. + > [!NOTE] + > Visual Studio automatically inserts the `` and `` tags and positions your cursor within these tags after you type the `///` delimiter in the code editor. You can turn this feature on or off in the [Options dialog box](/visualstudio/ide/reference/options-text-editor-csharp-advanced). +- `/** */` Multiline delimiters: The `/** */` delimiters have the following formatting rules: + - On the line that contains the `/**` delimiter, if the rest of the line is white space, the line isn't processed for comments. If the first character after the `/**` delimiter is white space, that white-space character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment. + - On the line that contains the `*/` delimiter, if there's only white space up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment. + - For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line. The pattern can consist of optional white space and an asterisk (`*`), followed by more optional white space. If the compiler finds a common pattern at the beginning of each line that doesn't begin with the `/**` delimiter or end with the `*/` delimiter, it ignores that pattern for each line. + - The only part of the following comment that's processed is the line that begins with ``. The three tag formats produce the same comments. + + ```csharp + /** text */ + + /** + text + */ + + /** + * text + */ + ``` + + - The compiler identifies a common pattern of " \* " at the beginning of the second and third lines. The pattern isn't included in the output. + + ```csharp + /** + * + * text */ + ``` + + - The compiler finds no common pattern in the following comment because the second character on the third line isn't an asterisk. All text on the second and third lines is processed as part of the comment. + + ```csharp + /** + * + text + */ + ``` + + - The compiler finds no pattern in the following comment for two reasons. First, the number of spaces before the asterisk isn't consistent. Second, the fifth line begins with a tab, which doesn't match spaces. All text from lines two through five is processed as part of the comment. + + + ```csharp + /** + * + * text + * text2 + * + */ + ``` + + +To refer to XML elements (for example, your function processes specific XML elements that you want to describe in an XML documentation comment), you can use the standard quoting mechanism (`<` and `>`). To refer to generic identifiers in code reference (`cref`) elements, you can use either the escape characters (for example, `cref="List<T>"`) or braces (`cref="List{T}"`). As a special case, the compiler parses the braces as angle brackets to make the documentation comment less cumbersome to author when referring to generic identifiers. + +> [!NOTE] +> The XML documentation comments are not metadata; they are not included in the compiled assembly and therefore they are not accessible through reflection. + +## Tools that accept XML documentation input + +The following tools create output from XML comments: + +- [DocFX](https://dotnet.github.io/docfx/): *DocFX* is an API documentation generator for .NET, which currently supports C#, Visual Basic, and F#. It also allows you to customize the generated reference documentation. DocFX builds a static HTML website from your source code and Markdown files. Also, DocFX provides you the flexibility to customize the layout and style of your website through templates. You can also create custom templates. +- [Sandcastle](https://github.com/EWSoftware/SHFB): The *Sandcastle tools* create help files for managed class libraries containing both conceptual and API reference pages. The Sandcastle tools are command-line based and have no GUI front-end, project management features, or automated build process. The Sandcastle Help File Builder provides standalone GUI and command-line based tools to build a help file in an automated fashion. A Visual Studio integration package is also available for it so that help projects can be created and managed entirely from within Visual Studio. +- [Doxygen](https://github.com/doxygen/doxygen): *Doxygen* generates an on-line documentation browser (in HTML) or an off-line reference manual (in LaTeX) from a set of documented source files. There's also support for generating output in RTF (MS Word), PostScript, hyperlinked PDF, compressed HTML, DocBook, and Unix man pages. You can configure Doxygen to extract the code structure from undocumented source files. + +### ID strings + +Each type or member is stored in an element in the output XML file. Each of those elements has a unique ID string that identifies the type or member. The ID string must account for operators, parameters, return values, generic type parameters, `ref`, `in`, and `out` parameters. To encode all those potential elements, the compiler follows clearly defined rules for generating the ID strings. Programs that process the XML file use the ID string to identify the corresponding .NET metadata or reflection item that the documentation applies to. + +The compiler observes the following rules when it generates the ID strings: + +- No white space is in the string. +- The first part of the string identifies the kind of member using a single character followed by a colon. The following member types are used: + + |Character|Member type|Notes| + |---------------|-----------------|-| + |N|namespace|You can't add documentation comments to a namespace, but you can make cref references to them, where supported.| + |T|type|A type is a class, interface, struct, enum, or delegate.| + |F|field| + |P|property|Includes indexers or other indexed properties.| + |M|method|Includes special methods, such as constructors and operators.| + |E|event| + |!|error string|The rest of the string provides information about the error. The C# compiler generates error information for links that cannot be resolved.| + +- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type(s), and namespace are separated by periods. If the name of the item itself has periods, they're replaced by the hash-sign ('#'). It's assumed that no item has a hash-sign directly in its name. For example, the fully qualified name of the String constructor is "System.String.#ctor". +- For properties and methods, the parameter list enclosed in parentheses follows. If there are no parameters, no parentheses are present. The parameters are separated by commas. The encoding of each parameter follows directly how it's encoded in a .NET signature (See for definitions of the all caps elements in the following list): + - Base types. Regular types (`ELEMENT_TYPE_CLASS` or `ELEMENT_TYPE_VALUETYPE`) are represented as the fully qualified name of the type. + - Intrinsic types (for example, `ELEMENT_TYPE_I4`, `ELEMENT_TYPE_OBJECT`, `ELEMENT_TYPE_STRING`, `ELEMENT_TYPE_TYPEDBYREF`, and `ELEMENT_TYPE_VOID`) are represented as the fully qualified name of the corresponding full type. For example, `System.Int32` or `System.TypedReference`. + - `ELEMENT_TYPE_PTR` is represented as a '\*' following the modified type. + - `ELEMENT_TYPE_BYREF` is represented as a '\@' following the modified type. + - `ELEMENT_TYPE_CMOD_OPT` is represented as a '!' and the fully qualified name of the modifier class, following the modified type. + - `ELEMENT_TYPE_SZARRAY` is represented as "[]" following the element type of the array. + - `ELEMENT_TYPE_ARRAY` is represented as [*lowerbound*:`size`,*lowerbound*:`size`] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size isn't specified, it's omitted. If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. For example, a two-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:]. +- For conversion operators only (`op_Implicit` and `op_Explicit`), the return value of the method is encoded as a `~` followed by the return type. For example: + `` is the tag for the cast operator `public static explicit operator int (decimal value);` declared in the `System.Decimal` class. +- For generic types, the name of the type is followed by a backtick and then a number that indicates the number of generic type parameters. For example: + `` is the tag for a type that is defined as `public class SampleClass`. + For methods that take generic types as parameters, the generic type parameters are specified as numbers prefaced with backticks (for example \`0,\`1). Each number represents a zero-based array notation for the type's generic parameters. + - `ELEMENT_TYPE_PINNED` is represented as a '^' following the modified type. The C# compiler never generates this encoding. + - `ELEMENT_TYPE_CMOD_REQ` is represented as a '|' and the fully qualified name of the modifier class, following the modified type. The C# compiler never generates this encoding. + - `ELEMENT_TYPE_GENERICARRAY` is represented as "[?]" following the element type of the array. The C# compiler never generates this encoding. + - `ELEMENT_TYPE_FNPTR` is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The C# compiler never generates this encoding. + - The following signature components aren't represented because they aren't used to differentiate overloaded methods: + - calling convention + - return type + - `ELEMENT_TYPE_SENTINEL` + +The following examples show how the ID strings for a class and its members are generated: + +:::code language="csharp" source="./snippets/xmldoc/idstrings.cs"::: + +## C# language specification + +For more information, see the [C# Language Specification](~/_csharplang/spec/documentation-comments.md) annex on documentation comments. diff --git a/docs/csharp/language-reference/xmldoc/recommended-tags.md b/docs/csharp/language-reference/xmldoc/recommended-tags.md new file mode 100644 index 0000000000000..a16158132fb38 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/recommended-tags.md @@ -0,0 +1,389 @@ +--- +title: "Recommended XML documentation tags for a class and its members" +description: This article provides the syntax and definitions for recommended tags for XML documentation. +ms.date: 07/12/2021 +f1_keywords: + - "" + - "summary" + - "remarks" + - "" + - "returns" + - "" + - "param" + - "" + - "paramref" + - "" + - "" + - "exception" + - "" + - "typeparam" + - "typeparamref" + - "inheritdoc" + - "" + - "include" + - "" + - "c" + - "" + - "code" + - "" + - "" + - "example" + - "list" + - "" + - "" + - "para" + - "" + - "see" + - "" + - "seealso" +helpviewer_keywords: + - "XML [C#], tags" + - "XML documentation [C#], tags" + - "C# language, XML documentation features" + - " C# XML tag" + - "summary C# XML tag" + - "remarks C# XML tag" + - " C# XML tag" + - " C# XML tag" + - "returns C# XML tag" + - " C# XML tag" + - "param C# XML tag" + - " C# XML tag" + - "paramref C# XML tag" + - " C# XML tag" + - "value C# XML tag" + - "cref [C#]" + - " C# XML tag" + - "exception C# XML tag" + - " C# XML tag" + - "typeparam C# XML tag" + - "typeparamref C# XML tag" + - " C# XML tag" + - " C# XML tag" + - "inheritdoc C# XML tag" + - " C# XML tag" + - "include C# XML tag" + - "text, marking as code [C#]" + - "code, marking text as [C#]" + - "c C# XML tag" + - " C# XML tag" + - "code XML tag" + - " C# XML tag" + - " C# XML tag" + - "example C# XML tag" + - "list C# XML tag" + - "listheader C# XML tag" + - " C# XML tag" + - "item C# XML tag" + - " C# XML tag" + - " C# XML tag" + - " C# XML tag" + - "para C# XML tag" + - "cref [C#], tag" + - " C# XML tag" + - "cross-references [C#]" + - "see C# XML tag" + - "cref" + - "cref [C#], see also" + - "seealso C# XML tag" + - "cref [C#]" + - "cross-references [C#], tags" + - " C# XML tag" +--- +# Recommend XML tags for C# documentation comments + +C# documentation comments use XML elements to define the structure of the output documentation. One consequence of this feature is that you can add any valid XML in your documentation comments. The C# compiler copies these elements into the output XML file. While you can use any valid XML in your comments (including any valid HTML element), documenting code is recommended for many reasons. + +What follows are some recommendations, general use case scenarios, and things that you should know when using XML documentation tags in your C# code. While you can put any tags into your documentation comments, this article describes the recommended tags for the most common language constructs. In all cases, you should adhere to these recommendations: + +- For the sake of consistency, all publicly visible types and their public members should be documented. +- Private members can also be documented using XML comments. However, it exposes the inner (potentially confidential) workings of your library. +- At a bare minimum, types and their members should have a `` tag because its content is needed for IntelliSense. +- Documentation text should be written using complete sentences ending with full stops. +- Partial classes are fully supported, and documentation information will be concatenated into a single entry for each type. + +XML documentation starts with `///`. When you create a new project, the templates put some starter `///` lines in for you. The processing of these comments has some restrictions: + +- The documentation must be well-formed XML. If the XML isn't well formed, the compiler generates a warning. The documentation file will contain a comment that says that an error was encountered. +- Some of the recommended tags have special meanings: + - The `` tag is used to describe parameters. If used, the compiler verifies that the parameter exists and that all parameters are described in the documentation. If the verification fails, the compiler issues a warning. + - The `cref` attribute can be attached to any tag to reference a code element. The compiler verifies that this code element exists. If the verification fails, the compiler issues a warning. The compiler respects any `using` statements when it looks for a type described in the `cref` attribute. + - The `` tag is used by IntelliSense inside Visual Studio to display additional information about a type or member. + > [!NOTE] + > The XML file does not provide full information about the type and members (for example, it does not contain any type information). To get full information about a type or member, use the documentation file together with reflection on the actual type or member. +- Developers are free to create their own set of tags. The compiler will copy these to the output file. + +Some of the recommended tags can be used on any language element. Others have more specialized usage. Finally, some of the tags are used to format text in your documentation. This article describes the recommended tags organized by their use. + +The compiler verifies the syntax of the elements followed by a single \* in the following list. Visual Studio provides IntelliSense for the tags verified by the compiler and all tags followed by \*\* in the following list. In addition to the tags listed here, the compiler and Visual Studio validate the ``, ``, ``, `
`, and `` tags. The compiler also validates ``, which is deprecated HTML. + +- [General Tags](#general-tags) used for multiple elements - These tags are the minimum set for any API. + - [``](#summary): The value of this element is displayed in IntelliSense in Visual Studio. + - [``](#remarks) \*\* +- [Tags used for members](#document-members) - These tags are used when documenting methods and properties. + - [``](#returns): The value of this element is displayed in IntelliSense in Visual Studio. + - [``](#param) \*: The value of this element is displayed in IntelliSense in Visual Studio. + - [``](#paramref) + - [``](#exception) \* + - [``](#value): The value of this element is displayed in IntelliSense in Visual Studio. +- [Format documentation output](#format-documentation-output) - These tags provide formatting directions for tools that generate documentation. + - [``](#para) + - [``](#list) + - [``](#c) + - [``](#code) + - [``](#example) \*\* +- [Reuse documentation text](#reuse-documentation-text) - These tags provide tools that make it easier to reuse XML comments. + - [``](#inheritdoc) \*\* + - [``](#include) \* +- [Generate links and references](#generate-links-and-references) - These tags generate links to other documentation. + - [``](#see) \* + - [``](#seealso) \* + - [``](#cref-attribute) + - [``](#href-attribute) +- [Tags for generic types and methods](#generic-types-and-methods) - These tags are used only on generic types and methods + - [``](#typeparam) \*: The value of this element is displayed in IntelliSense in Visual Studio. + - [``](#typeparamref) + +> [!NOTE] +> Documentation comments cannot be applied to a namespace. + +If you want angle brackets to appear in the text of a documentation comment, use the HTML encoding of `<` and `>`, which is `<` and `>` respectively. This encoding is shown in the following example. + +```csharp +/// +/// This property always returns a value < 1. +/// +``` + +## General tags + +### \ + +```xml +description +``` + +The `` tag should be used to describe a type or a type member. Use [\](#remarks) to add supplemental information to a type description. Use the [cref attribute](#cref-attribute) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. The text for the `` tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser window. + +### \ + +```xml + +description + +``` + +The `` tag is used to add information about a type or a type member, supplementing the information specified with [\](#summary). This information is displayed in the Object Browser window. This tag may include more lengthy explanations. You may find that using `CDATA` sections for markdown make writing it more convenient. Tools such as [docfx](https://dotnet.github.io/docfx/) process the markdown text in `CDATA` sections. + +## Document members + +### \ + +```xml +description +``` + +The `` tag should be used in the comment for a method declaration to describe the return value. + +### \ + +```xml +description +``` + +- `name`: The name of a method parameter. Enclose the name in double quotation marks (" "). The names for parameters must match the API signature. If one or more parameter aren't covered, the compiler issues a warning. The compiler also issues a warning if the value of `name` doesn't match a formal parameter in the method declaration. + +The `` tag should be used in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple `` tags. The text for the `` tag is displayed in IntelliSense, the Object Browser, and the Code Comment Web Report. + +### \ + +```xml + +``` + +- `name`: The name of the parameter to refer to. Enclose the name in double quotation marks (" "). + +The `` tag gives you a way to indicate that a word in the code comments, for example in a `` or `` block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font. + +### \ + +```xml +description +``` + +- cref = "`member`": A reference to an exception that is available from the current compilation environment. The compiler checks that the given exception exists and translates `member` to the canonical element name in the output XML. `member` must appear within double quotation marks (" "). + +The `` tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers. + +### \ + +```xml +property-description +``` + +The `` tag lets you describe the value that a property represents. When you add a property via code wizard in the Visual Studio .NET development environment, it adds a [\](#summary) tag for the new property. You manually add a `` tag to describe the value that the property represents. + +## Format documentation output + +### \ + +```xml + + + This is an introductory paragraph. + + + This paragraph contains more details. + + +``` + +The `` tag is for use inside a tag, such as [\](#summary), [\](#remarks), or [\](#returns), and lets you add structure to the text. The `` tag creates a double spaced paragraph. Use the `
` tag if you want a single spaced paragraph. + +### \ + +```xml + + + term + description + + + Assembly + The library or executable built from a compilation. + + +``` + +The `` block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for `term` in the heading. Each item in the list is specified with an `` block. When creating a definition list, you'll need to specify both `term` and `description`. However, for a table, bulleted list, or numbered list, you only need to supply an entry for `description`. A list or table can have as many `` blocks as needed. + +### \ + +```xml +text +``` + +The `` tag gives you a way to indicate that text within a description should be marked as code. Use [\](#code) to indicate multiple lines as code. + +### \ + +```xml + + var index = 5; + index++; + +``` + +The `` tag is used to indicate multiple lines of code. Use [\](#c) to indicate that single-line text within a description should be marked as code. + +### \ + +```xml + +This shows how to increment an integer. + + var index = 5; + index++; + + +``` + +The `` tag lets you specify an example of how to use a method or other library member. An example commonly involves using the [\](#code) tag. + +## Reuse documentation text + +### \ + +```xml + +``` + +Inherit XML comments from base classes, interfaces, and similar methods. Using `inheritdoc` eliminates unwanted copying and pasting of duplicate XML comments and automatically keeps XML comments synchronized. Note that when you add the `` tag to a type, all members will inherit the comments as well. + +- `cref`: Specify the member to inherit documentation from. Already defined tags on the current member are not overridden by the inherited ones. +- `path`: The XPath expression query that will result in a node set to show. You can use this attribute to filter the tags to include or exclude from the inherited documentation. + +Add your XML comments in base classes or interfaces and let inheritdoc copy the comments to implementing classes. Add your XML comments to your synchronous methods and let inheritdoc copy the comments to your asynchronous versions of the same methods. If you want to copy the comments from a specific member, you use the `cref` attribute to specify the member. + +### \ + +```xml + +``` + +- `filename`: The name of the XML file containing the documentation. The file name can be qualified with a path relative to the source code file. Enclose `filename` in single quotation marks (' '). +- `tagpath`: The path of the tags in `filename` that leads to the tag `name`. Enclose the path in single quotation marks (' '). +- `name`: The name specifier in the tag that precedes the comments; `name` will have an `id`. +- `id`: The ID for the tag that precedes the comments. Enclose the ID in double quotation marks (" "). + +The `` tag lets you refer to comments in another file that describe the types and members in your source code. Including an external file is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out. The `` tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your `` use. + +## Generate links and references + +### \ + +```csharp +/// +// or +/// Link text +// or +/// Link Text +// or +/// +``` + +- `cref="member"`: A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes `member` to the element name in the output XML. Place *member* within double quotation marks (" "). You can provide different link text for a "cref", by using a separate closing tag. +- `href="link"`: A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. +- `langword="keyword"`: A language keyword, such as `true`. + +The `` tag lets you specify a link from within text. Use [\](#seealso) to indicate that text should be placed in a See Also section. Use the [cref attribute](#cref-attribute) to create internal hyperlinks to documentation pages for code elements. You include the type parameters to specify a reference to a generic type or method, such as `cref="cref="IDictionary{T, U}"`. Also, ``href`` is a valid attribute that will function as a hyperlink. + +### \ + +```csharp +/// +// or +/// Link Text +``` + +- `cref="member"`: A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes `member` to the element name in the output XML. `member` must appear within double quotation marks (" "). +- `href="link"`: A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. + +The `` tag lets you specify the text that you might want to appear in a **See Also** section. Use [\](#see) to specify a link from within text. You cannot nest the `seealso` tag inside the `summary` tag. + +### cref attribute + +The `cref` attribute in an XML documentation tag means "code reference." It specifies that the inner text of the tag is a code element, such as a type, method, or property. Documentation tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) use the `cref` attributes to automatically generate hyperlinks to the page where the type or member is documented. + +### href attribute + +The `href` attribute means a reference to a web page. You can use it to directly reference online documentation about your API or library. + +## Generic types and methods + +### \ + +```xml +The type returned from this method +``` + +- `TResult`: The name of the type parameter. Enclose the name in double quotation marks (" "). + +The `` tag should be used in the comment for a generic type or method declaration to describe a type parameter. Add a tag for each type parameter of the generic type or method. The text for the `` tag will be displayed in IntelliSense. + +### \ + +```xml + +``` + +- `TKey`: The name of the type parameter. Enclose the name in double quotation marks (" "). + +Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics. + +### User-defined tags + +All the tags outlined above represent those tags that are recognized by the C# compiler. However, a user is free to define their own tags. +Tools like Sandcastle bring support for extra tags like [\](https://ewsoftware.github.io/XMLCommentsGuide/html/81bf7ad3-45dc-452f-90d5-87ce2494a182.htm) and [\](https://ewsoftware.github.io/XMLCommentsGuide/html/4302a60f-e4f4-4b8d-a451-5f453c4ebd46.htm), +and even support [documenting namespaces](https://ewsoftware.github.io/XMLCommentsGuide/html/BD91FAD4-188D-4697-A654-7C07FD47EF31.htm). +Custom or in-house documentation generation tools can also be used with the standard tags, and multiple output formats from HTML to PDF can be supported. diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/DocComments.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/DocComments.cs new file mode 100644 index 0000000000000..193f88e6eedef --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/DocComments.cs @@ -0,0 +1,314 @@ +using System; + +//----------------------------------------------------------------------------- +namespace XmlTags +{ + // + /// + /// Every class and member should have a one sentence + /// summary describing its purpose. + /// + /// + /// You can expand on that one sentence summary to + /// provide more information for readers. In this case, + /// the ExampleClass provides different C# + /// elements to show how you would add documentation + ///comments for most elements in a typical class. + /// + /// The remarks can add multiple paragraphs, so you can + /// write detailed information for developers that use + /// your work. You should add everything needed for + /// readers to be successful. This class contains + /// examples for the following: + /// + /// + /// + /// Summary + /// + /// This should provide a one sentence summary of the class or member. + /// + /// + /// + /// Remarks + /// + /// This is typically a more detailed description of the class or member + /// + /// + /// + /// para + /// + /// The para tag separates a section into multiple paragraphs + /// + /// + /// + /// list + /// + /// Provides a list of terms or elements + /// + /// + /// + /// returns, param + /// + /// Used to describe parameters and return values + /// + /// + /// + /// value + /// Used to describe properties + /// + /// + /// exception + /// + /// Used to describe exceptions that may be thrown + /// + /// + /// + /// c, cref, see, seealso + /// + /// These provide code style and links to other + /// documentation elements + /// + /// + /// + /// example, code + /// + /// These are used for code examples + /// + /// + /// + /// + /// The list above uses the "table" style. You could + /// also use the "bullet" or "number" style. Neither + /// would typically use the "term" element. + ///
+ /// Note: paragraphs are double spaced. Use the *br* + /// tag for single spaced lines. + /// + /// + public class ExampleClass + { + /// + /// The Label property represents a label + /// for this instance. + /// + /// + /// The is a + /// that you use for a label. + /// + /// Note that there isn't a way to provide a "cref" to + /// each accessor, only to the property itself. + /// + /// + public string Label + { + get; + set; + } + + /// + /// Adds two integers and returns the result. + /// + /// + /// The sum of two integers. + /// + /// + /// The left operand of the addition. + /// + /// + /// The right operand of the addition. + /// + /// + /// + /// int c = Math.Add(4, 5); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// + /// Thrown when one parameter is + /// MaxValue and the other is + /// greater than 0. + /// Note that here you can also use + /// + /// to point a web page instead. + /// + /// for a list of all + /// the tags in these examples. + /// + public static int Add(int left, int right) + { + if ((left == int.MaxValue && right > 0) || (right == int.MaxValue && left > 0)) + throw new System.OverflowException(); + + return left + right; + } + } + + /// + /// This is an example of a positional record. + /// + /// + /// There isn't a way to add XML comments for properties + /// created for positional records, yet. The language + /// design team is still considering what tags should + /// be supported, and where. Currently, you can use + /// the "param" tag to describe the parameters to the + /// primary constructor. + /// + /// + /// This tag will apply to the primary constructor parameter. + /// + /// + /// This tag will apply to the primary constructor parameter. + /// + public record Person(string FirstName, string LastName); +} +// + +namespace InheritDoc +{ + // + /// + /// A summary about this class. + /// + /// + /// These remarks would explain more about this class. + /// In this example, these comments also explain the + /// general information about the derived class. + /// + public class MainClass + { + } + + /// + public class DerivedClass : MainClass + { + } + + /// + /// This interface would describe all the methods in + /// its contract. + /// + /// + /// While elided for brevity, each method or property + /// in this interface would contain docs that you want + /// to duplicate in each implementing class. + /// + public interface ITestInterface + { + /// + /// This method is part of the test interface. + /// + /// + /// This content would be inherited by classes + /// that implement this interface when the + /// implementing class uses "inheritdoc" + /// + /// The value of + /// The argument to the method + int Method(int arg); + } + + /// + public class ImplementingClass : ITestInterface + { + // doc comments are inherited here. + public int Method(int arg) => arg; + } + + /// + /// This class shows hows you can "inherit" the doc + /// comments from one method in another method. + /// + /// + /// You can inherit all comments, or only a specific tag, + /// represented by an xpath expression. + /// + public class InheritOnlyReturns + { + /// + /// In this example, this summary is only visible for this method. + /// + /// A boolean + public static bool MyParentMethod(bool x) { return x; } + + /// + public static bool MyChildMethod() { return false; } + } + + /// + /// This class shows an example ofsharing comments across methods. + /// + public class InheritAllButRemarks + { + /// + /// In this example, this summary is visible on all the methods. + /// + /// + /// The remarks can be inherited by other methods + /// using the xpath expression. + /// + /// A boolean + public static bool MyParentMethod(bool x) { return x; } + + /// + public static bool MyChildMethod() { return false; } + } + // + + // + /// + class Test + { + static void Main() + { + } + } + + /// + class Test2 + { + public void Test() + { + } + } + // +} + +// +/// +/// This is a generic class. +/// +/// +/// This example shows how to specify the +/// type as a cref attribute. +/// In generic classes and methods, you'll often want to reference the +/// generic type, or the type parameter. +/// +class GenericClass +{ + // Fields and members. +} + +/// +/// This shows examples of typeparamref and typeparam tags +/// +public class ParamsAndParamRefs +{ + /// + /// The GetGenericValue method. + /// + /// + /// This sample shows how to specify the + /// method as a cref attribute. + /// The parameter and return value are both of an arbitrary type, + /// + /// + public static T GetGenericValue(T para) + { + return para; + } +} +// diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/Program.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/Program.cs new file mode 100644 index 0000000000000..f614f1f23f13d --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/Program.cs @@ -0,0 +1,14 @@ +using System; + +namespace xmldoc +{ + class Program + { + static void Main(string[] args) + { + Console.WriteLine("Hello World!"); + } + } + + +} diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/idstrings.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/idstrings.cs new file mode 100644 index 0000000000000..29486c3588fbf --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/idstrings.cs @@ -0,0 +1,110 @@ +namespace MyNamespace +{ + /// + /// Enter description here for class X. + /// ID string generated is "T:MyNamespace.X". + /// + public unsafe class MyClass + { + /// + /// Enter description here for the first constructor. + /// ID string generated is "M:MyNamespace.MyClass.#ctor". + /// + public MyClass() { } + + /// + /// Enter description here for the second constructor. + /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)". + /// + /// Describe parameter. + public MyClass(int i) { } + + /// + /// Enter description here for field message. + /// ID string generated is "F:MyNamespace.MyClass.message". + /// + public string message; + + /// + /// Enter description for constant PI. + /// ID string generated is "F:MyNamespace.MyClass.PI". + /// + public const double PI = 3.14; + + /// + /// Enter description for method func. + /// ID string generated is "M:MyNamespace.MyClass.func". + /// + /// Describe return value. + public int func() { return 1; } + + /// + /// Enter description for method someMethod. + /// ID string generated is "M:MyNamespace.MyClass.someMethod(System.String,System.Int32@,System.Void*)". + /// + /// Describe parameter. + /// Describe parameter. + /// Describe parameter. + /// Describe return value. + public int someMethod(string str, ref int nm, void* ptr) { return 1; } + + /// + /// Enter description for method anotherMethod. + /// ID string generated is "M:MyNamespace.MyClass.anotherMethod(System.Int16[],System.Int32[0:,0:])". + /// + /// Describe parameter. + /// Describe parameter. + /// Describe return value. + public int anotherMethod(short[] array1, int[,] array) { return 0; } + + /// + /// Enter description for operator. + /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)". + /// + /// Describe parameter. + /// Describe parameter. + /// Describe return value. + public static MyClass operator +(MyClass first, MyClass second) { return first; } + + /// + /// Enter description for property. + /// ID string generated is "P:MyNamespace.MyClass.prop". + /// + public int prop { get { return 1; } set { } } + + /// + /// Enter description for event. + /// ID string generated is "E:MyNamespace.MyClass.OnHappened". + /// + public event Del OnHappened; + + /// + /// Enter description for index. + /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)". + /// + /// Describe parameter. + /// + public int this[string s] { get { return 1; } } + + /// + /// Enter description for class Nested. + /// ID string generated is "T:MyNamespace.MyClass.Nested". + /// + public class Nested { } + + /// + /// Enter description for delegate. + /// ID string generated is "T:MyNamespace.MyClass.Del". + /// + /// Describe parameter. + public delegate void Del(int i); + + /// + /// Enter description for operator. + /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.X)~System.Int32". + /// + /// Describe parameter. + /// Describe return value. + public static explicit operator int(MyClass myParameter) { return 1; } + } +} diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/include-tag.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/include-tag.cs new file mode 100644 index 0000000000000..a10f502097292 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/include-tag.cs @@ -0,0 +1,77 @@ +namespace IncludeTag +{ + + /* + The main Math class + Contains all methods for performing basic math functions + */ + /// + public class Math + { + // Adds two integers and returns the result + /// + public static int Add(int a, int b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Adds two doubles and returns the result + /// + public static double Add(double a, double b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Subtracts an integer from another and returns the result + /// + public static int Subtract(int a, int b) + { + return a - b; + } + + // Subtracts a double from another and returns the result + /// + public static double Subtract(double a, double b) + { + return a - b; + } + + // Multiplies two integers and returns the result + /// + public static int Multiply(int a, int b) + { + return a * b; + } + + // Multiplies two doubles and returns the result + /// + public static double Multiply(double a, double b) + { + return a * b; + } + + // Divides an integer by another and returns the result + /// + public static int Divide(int a, int b) + { + return a / b; + } + + // Divides a double by another and returns the result + /// + public static double Divide(double a, double b) + { + return a / b; + } + } +} diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/include.xml b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/include.xml new file mode 100644 index 0000000000000..d22fc1daf43d4 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/include.xml @@ -0,0 +1,215 @@ + + + + + The main Math class. + Contains all methods for performing basic math functions. + + + This class can add, subtract, multiply and divide. + These operations can be performed on both integers and doubles. + + + + + Adds two integers and + and returns the result. + + + The sum of two integers. + + + + int c = Math.Add(4, 5); + if (c > 10) + { + Console.WriteLine(c); + } + + + Thrown when one + parameter is max + and the other is greater than 0. + See to add doubles. + + + + An integer. + An integer. + + + + Adds two doubles and + and returns the result. + + + The sum of two doubles. + + + + double c = Math.Add(4.5, 5.4); + if (c > 10) + { + Console.WriteLine(c); + } + + + Thrown when one parameter is max + and the other is greater than 0. + See to add integers. + + + + A double precision number. + A double precision number. + + + + Subtracts from and + returns the result. + + + The difference between two integers. + + + + int c = Math.Subtract(4, 5); + if (c > 1) + { + Console.WriteLine(c); + } + + + See to subtract doubles. + + + + An integer. + An integer. + + + + Subtracts a double from another + double and returns the result. + + + The difference between two doubles. + + + + double c = Math.Subtract(4.5, 5.4); + if (c > 1) + { + Console.WriteLine(c); + } + + + See to subtract integers. + + + + A double precision number. + A double precision number. + + + + Multiplies two integers and + and returns the result. + + + The product of two integers. + + + + int c = Math.Multiply(4, 5); + if (c > 100) + { + Console.WriteLine(c); + } + + + See to multiply doubles. + + + + An integer. + An integer. + + + + Multiplies two doubles and + and returns the result. + + + The product of two doubles. + + + + double c = Math.Multiply(4.5, 5.4); + if (c > 100.0) + { + Console.WriteLine(c); + } + + + See to multiply integers. + + + + A double precision number. + A double precision number. + + + + Divides an integer by another integer + and returns the result. + + + The quotient of two integers. + + + + int c = Math.Divide(4, 5); + if (c > 1) + { + Console.WriteLine(c); + } + + + + Thrown when is equal to 0. + + See to divide doubles. + + + + An integer dividend. + An integer divisor. + + + + Divides a double by another + double and returns the result. + + + The quotient of two doubles. + + + + double c = Math.Divide(4.5, 5.4); + if (c > 1.0) + { + Console.WriteLine(c); + } + + + Thrown when is equal to 0. + See to divide integers. + + + + A double precision dividend. + A double precision divisor. + + + diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/tagged-library.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/tagged-library.cs new file mode 100644 index 0000000000000..b1490b3a51908 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/tagged-library.cs @@ -0,0 +1,292 @@ +namespace TaggedLibrary +{ + /* + The main Math class + Contains all methods for performing basic math functions + */ + /// + /// The main Math class. + /// Contains all methods for performing basic math functions. + /// + /// + /// Add + /// Addition Operation + /// + /// + /// Subtract + /// Subtraction Operation + /// + /// + /// Multiply + /// Multiplication Operation + /// + /// + /// Divide + /// Division Operation + /// + /// + /// + /// + /// + /// This class can add, subtract, multiply and divide. + /// + /// + /// These operations can be performed on both + /// integers and doubles. + /// + /// + public class Math + { + // Adds two integers and returns the result + /// + /// Adds two integers and + /// and returns the result. + /// + /// + /// The sum of two integers. + /// + /// + /// + /// int c = Math.Add(4, 5); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// + /// Thrown when one parameter is and the other + /// is greater than 0. + /// + /// See to add doubles. + /// + /// + /// + /// An integer. + /// An integer. + public static int Add(int a, int b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || + (b == int.MaxValue && a > 0)) + { + throw new System.OverflowException(); + } + return a + b; + } + + // Adds two doubles and returns the result + /// + /// Adds two doubles and + /// and returns the result. + /// + /// + /// The sum of two doubles. + /// + /// + /// + /// double c = Math.Add(4.5, 5.4); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// + /// Thrown when one parameter is max and the other + /// is greater than 0. + /// See to add integers. + /// + /// + /// + /// A double precision number. + /// A double precision number. + public static double Add(double a, double b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == double.MaxValue && b > 0) + || (b == double.MaxValue && a > 0)) + { + throw new System.OverflowException(); + } + + return a + b; + } + + // Subtracts an integer from another and returns the result + /// + /// Subtracts from + /// and returns the result. + /// + /// + /// The difference between two integers. + /// + /// + /// + /// int c = Math.Subtract(4, 5); + /// if (c > 1) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to subtract doubles. + /// + /// + /// + /// An integer. + /// An integer. + public static int Subtract(int a, int b) + { + return a - b; + } + + // Subtracts a double from another and returns the result + /// + /// Subtracts a double from another + /// double and returns the result. + /// + /// + /// The difference between two doubles. + /// + /// + /// + /// double c = Math.Subtract(4.5, 5.4); + /// if (c > 1) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to subtract integers. + /// + /// + /// + /// A double precision number. + /// A double precision number. + public static double Subtract(double a, double b) + { + return a - b; + } + + // Multiplies two integers and returns the result + /// + /// Multiplies two integers + /// and and returns the result. + /// + /// + /// The product of two integers. + /// + /// + /// + /// int c = Math.Multiply(4, 5); + /// if (c > 100) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to multiply doubles. + /// + /// + /// + /// An integer. + /// An integer. + public static int Multiply(int a, int b) + { + return a * b; + } + + // Multiplies two doubles and returns the result + /// + /// Multiplies two doubles and + /// and returns the result. + /// + /// + /// The product of two doubles. + /// + /// + /// + /// double c = Math.Multiply(4.5, 5.4); + /// if (c > 100.0) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to multiply integers. + /// + /// + /// + /// A double precision number. + /// A double precision number. + public static double Multiply(double a, double b) + { + return a * b; + } + + // Divides an integer by another and returns the result + /// + /// Divides an integer by another + /// integer and returns the result. + /// + /// + /// The quotient of two integers. + /// + /// + /// + /// int c = Math.Divide(4, 5); + /// if (c > 1) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// + /// Thrown when is equal to 0. + /// + /// See to divide doubles. + /// + /// + /// + /// An integer dividend. + /// An integer divisor. + public static int Divide(int a, int b) + { + return a / b; + } + + // Divides a double by another and returns the result + /// + /// Divides a double by another double + /// and returns the result. + /// + /// + /// The quotient of two doubles. + /// + /// + /// + /// double c = Math.Divide(4.5, 5.4); + /// if (c > 1.0) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// + /// Thrown when is equal to 0. + /// + /// See to divide integers. + /// + /// + /// + /// A double precision dividend. + /// A double precision divisor. + public static double Divide(double a, double b) + { + return a / b; + } + } +} diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/xml_include_tag.xml b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/xml_include_tag.xml new file mode 100644 index 0000000000000..48b0ea53f3fb5 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/xml_include_tag.xml @@ -0,0 +1,12 @@ + + + + The summary for this type. + + + + + The summary for this other type. + + + diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/xmldoc.csproj b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/xmldoc.csproj new file mode 100644 index 0000000000000..49b2ff086d381 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/xmldoc.csproj @@ -0,0 +1,11 @@ + + + + Exe + net5.0 + xmldoc.xml + true + xmldoc.Program + + + diff --git a/docs/csharp/misc/cs1570.md b/docs/csharp/misc/cs1570.md index 8cd9f516cae09..6063c796757e0 100644 --- a/docs/csharp/misc/cs1570.md +++ b/docs/csharp/misc/cs1570.md @@ -13,13 +13,13 @@ XML comment on 'construct' has badly formed XML — 'reason' When using [**DocumentationFile**](../language-reference/compiler-options/output.md#documentationfile), any comments in the source code must be in XML. Any error with your XML markup will generate CS1570. For example: -- If you are passing a string to a **cref**, such as in an [\](../programming-guide/xmldoc/exception.md) tag, the string must be enclosed in double quotation marks. +- If you are passing a string to a **cref**, such as in an [\](../language-reference/xmldoc/recommended-tags.md) tag, the string must be enclosed in double quotation marks. -- If you are using a tag, such as [\](../programming-guide/xmldoc/seealso.md), which does not have a closing tag, you must specify a forward slash before the closing angle bracket. +- If you're using a tag that doesn't have a closing tag, such as [\](../language-reference/xmldoc/recommended-tags.md), you must specify a forward slash before the closing angle bracket. - If you need to use a greater-than or less-than symbol in the text of description, you need to represent them with `>` or `<`. Alternatively, you can use CDATA. -- The file or path attribute on an [\](../programming-guide/xmldoc/include.md) tag was missing or improperly formed. +- The file or path attribute on an [\](../language-reference/xmldoc/recommended-tags.md) tag was missing or improperly formed. The following sample generates CS1570: diff --git a/docs/csharp/misc/cs1574.md b/docs/csharp/misc/cs1574.md index 3f7b4f910c05f..3fe6f3660345c 100644 --- a/docs/csharp/misc/cs1574.md +++ b/docs/csharp/misc/cs1574.md @@ -14,7 +14,7 @@ XML comment on 'construct' has syntactically incorrect cref attribute 'name' A string passed to a cref tag, for example, within an \ tag, referred to a member that is not available within the current build environment. The string that you pass to a cref tag must be the syntactically correct name of a member or field. - For more information, see [Recommended Tags for Documentation Comments](../programming-guide/xmldoc/recommended-tags-for-documentation-comments.md). + For more information, see [Recommended Tags for Documentation Comments](../language-reference/xmldoc/recommended-tags.md). The following sample generates CS1574: diff --git a/docs/csharp/misc/cs1584.md b/docs/csharp/misc/cs1584.md index 23d136bbd8ad6..73a627fd4f4e8 100644 --- a/docs/csharp/misc/cs1584.md +++ b/docs/csharp/misc/cs1584.md @@ -12,7 +12,7 @@ ms.assetid: 56c8f9bf-4cce-4269-b573-d60e5b11f9ab XML comment on 'member' has syntactically incorrect cref attribute 'invalid_syntax' - One of the parameters passed to a tag for documentation comments has invalid syntax. For more information, see [Recommended Tags for Documentation Comments](../programming-guide/xmldoc/recommended-tags-for-documentation-comments.md). + One of the parameters passed to a tag for documentation comments has invalid syntax. For more information, see [Recommended Tags for Documentation Comments](../language-reference/xmldoc/recommended-tags.md). ## Example diff --git a/docs/csharp/misc/cs1587.md b/docs/csharp/misc/cs1587.md index e6d3de5f3552a..3fff99bfd8392 100644 --- a/docs/csharp/misc/cs1587.md +++ b/docs/csharp/misc/cs1587.md @@ -12,7 +12,7 @@ ms.assetid: b27c2009-d485-43fd-a649-fbc15570d256 XML comment is not placed on a valid language element - Recommended tags for documentation comments are not allowed on all language elements. For example, a tag is not allowed on a namespace. For more information on XML comments, see [Recommended Tags for Documentation Comments](../programming-guide/xmldoc/recommended-tags-for-documentation-comments.md). + Recommended tags for documentation comments are not allowed on all language elements. For example, a tag is not allowed on a namespace. For more information on XML comments, see [Recommended Tags for Documentation Comments](../language-reference/xmldoc/recommended-tags.md). ## Example diff --git a/docs/csharp/misc/cs1589.md b/docs/csharp/misc/cs1589.md index f0371bf837ce0..1bbad2136957f 100644 --- a/docs/csharp/misc/cs1589.md +++ b/docs/csharp/misc/cs1589.md @@ -12,7 +12,7 @@ ms.assetid: bdc47124-93ae-4c6a-81b2-dde8ec4d0ab1 Unable to include XML fragment 'fragment' of file 'file' -- reason - The syntax (*fragment*) of a [\](../programming-guide/xmldoc/include.md) tag, which referenced a file (`file`), was incorrect for the specified ***reason***. + The syntax (*fragment*) of a [\](../language-reference/xmldoc/recommended-tags.md) tag, which referenced a file (`file`), was incorrect for the specified ***reason***. A malformed line will be placed in the generated XML file. diff --git a/docs/csharp/misc/cs1590.md b/docs/csharp/misc/cs1590.md index 4b13f1d7e54ea..14885dd82aec2 100644 --- a/docs/csharp/misc/cs1590.md +++ b/docs/csharp/misc/cs1590.md @@ -12,7 +12,7 @@ ms.assetid: 0d6e5594-d6a6-43bf-8aa8-a452fa5748df Invalid XML include element -- Missing file attribute - A path or doc attribute, passed to the [\](../programming-guide/xmldoc/include.md) tag, was missing or incomplete. + A path or doc attribute, passed to the [\](../language-reference/xmldoc/recommended-tags.md) tag, was missing or incomplete. The following sample generates CS1590: diff --git a/docs/csharp/misc/cs1592.md b/docs/csharp/misc/cs1592.md index 47af9ea192d19..2d90fda927a54 100644 --- a/docs/csharp/misc/cs1592.md +++ b/docs/csharp/misc/cs1592.md @@ -12,4 +12,4 @@ ms.assetid: 0a6bd30b-b5f2-424b-9683-568d32f3fb17 Badly formed XML in included comments file -- 'reason' - A problem, reported as ***reason***, was found in the file specified by the [\](../programming-guide/xmldoc/include.md) tag. + A problem, reported as ***reason***, was found in the file specified by the [\](../language-reference/xmldoc/recommended-tags.md) tag. diff --git a/docs/csharp/misc/cs1712.md b/docs/csharp/misc/cs1712.md index 51fdaa974d386..e3cd23c4dc256 100644 --- a/docs/csharp/misc/cs1712.md +++ b/docs/csharp/misc/cs1712.md @@ -12,7 +12,7 @@ ms.assetid: d9a8be26-c0ba-41fa-b082-1ce4ba7724b7 Type parameter 'type parameter' has no matching typeparam tag in the XML comment on 'type' (but other type parameters do) - The documentation of a generic type is missing a **typeparam** tag. For more information, see [\](../programming-guide/xmldoc/typeparam.md). + The documentation of a generic type is missing a **typeparam** tag. For more information, see [\](../language-reference/xmldoc/recommended-tags.md). ## Example diff --git a/docs/csharp/programming-guide/index.md b/docs/csharp/programming-guide/index.md index 43d11a3cb805d..c517aae707d40 100644 --- a/docs/csharp/programming-guide/index.md +++ b/docs/csharp/programming-guide/index.md @@ -57,7 +57,7 @@ This section provides detailed information on key C# language features and featu [Unsafe Code and Pointers](../language-reference/unsafe-code.md) - [XML Documentation Comments](./xmldoc/index.md) + [XML Documentation Comments](/dotnet/csharp/language-reference/xmldoc) ## Platform Sections diff --git a/docs/csharp/programming-guide/xmldoc/code-inline.md b/docs/csharp/programming-guide/xmldoc/code-inline.md deleted file mode 100644 index e991c4d6e4b60..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/code-inline.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag marks single-line text in a description as code, while indicates multiple lines. -ms.date: 07/20/2015 -f1_keywords: - - "c" - - "" -helpviewer_keywords: - - "text, marking as code [C#]" - - "code, marking text as [C#]" - - "c C# XML tag" - - " C# XML tag" -ms.assetid: aad5b16e-a29e-445e-bd0d-eea0b138d7b2 ---- -# \ (C# programming guide) - -## Syntax - -```xml -text -``` - -## Parameters - -- `text` - - The text you would like to indicate as code. - -## Remarks - -The `` tag gives you a way to indicate that text within a description should be marked as code. Use [\](./code.md) to indicate multiple lines as code. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#2](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#2)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/code.md b/docs/csharp/programming-guide/xmldoc/code.md deleted file mode 100644 index b42f48316a345..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/code.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag is used to indicate multiple lines of code, while marks single-line text in a description as code. -ms.date: 07/20/2015 -f1_keywords: - - "code" - - "" -helpviewer_keywords: - - "code XML tag" - - " C# XML tag" -ms.assetid: f235e3bc-a709-43cf-8a9f-bd57cabdf6da ---- -# \ (C# programming guide) - -## Syntax - -```xml -content -``` - -## Parameters - -- `content` - - The text you want marked as code. - -## Remarks - -The `` tag is used to indicate multiple lines of code. Use [\](./code-inline.md) to indicate that single-line text within a description should be marked as code. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -See the [\](./example.md) article for an example of how to use the `` tag. - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/cref-attribute.md b/docs/csharp/programming-guide/xmldoc/cref-attribute.md deleted file mode 100644 index 83975f405f607..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/cref-attribute.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "cref attribute - C# programming guide" -description: Learn about the cref attribute. The cref attribute means "code reference", and specifies that the inner text of the tag is a code element. -ms.date: 07/20/2015 -helpviewer_keywords: - - "cref [C#]" -ms.assetid: 66a6b0e5-b961-4504-a461-3a4cf481fc8b ---- -# cref attribute (C# programming guide) - -The `cref` attribute in an XML documentation tag means "code reference." It specifies that the inner text of the tag is a code element, such as a type, method, or property. Documentation tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) use the `cref` attributes to automatically generate hyperlinks to the page where the type or member is documented. - -## Example - -The following example shows `cref` attributes used in [\](./see.md) tags. - -[!code-csharp[csProgGuideDocComments#3](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#3)] - -When compiled, the program produces the following XML file. Notice that the `cref` attribute for the `GetZero` method, for example, has been transformed by the compiler to `"M:TestNamespace.TestClass.GetZero"`. The "M:" prefix means "method" and is a convention that is recognized by documentation tools such as DocFX and Sandcastle. For a complete list of prefixes, see [Processing the XML File](./processing-the-xml-file.md). - -```xml - - - - CRefTest - - - - - TestClass contains several cref examples. - - - - - This sample shows how to specify the constructor as a cref attribute. - - - - - This sample shows how to specify the constructor as a cref attribute. - - - - - The GetZero method. - - - This sample shows how to call the method. - - class TestClass - { - static int Main() - { - return GetZero(); - } - } - - - - - - The GetGenericValue method. - - - This sample shows how to specify the method as a cref attribute. - - - - - GenericClass. - - - This example shows how to specify the type as a cref attribute. - - - - -``` - -## See also - -- [XML documentation comments](./index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md b/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md deleted file mode 100644 index e3ac9067818fd..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Delimiters for documentation tags - C# programming guide" -description: Learn about delimiters for documentation tags. Delimiters indicate to the compiler where a documentation comment begins and ends. -ms.date: 07/20/2015 -helpviewer_keywords: - - "XML [C#], delimiters" - - "/** */ delimiters for C# documentation tags" - - "/// delimiter for C# documentation" -ms.assetid: 9b2bdd18-4f5c-4c0b-988e-fb992e0d233e ---- -# Delimiters for documentation tags (C# programming guide) - -The use of XML doc comments requires delimiters, which indicate to the compiler where a documentation comment begins and ends. You can use the following kinds of delimiters with the XML documentation tags: - -- `///` - - Single-line delimiter. This is the form that is shown in documentation examples and used by the C# project templates. If there is a white space character following the delimiter, that character is not included in the XML output. - - > [!NOTE] - > The Visual Studio integrated development environment (IDE) automatically inserts the `` and `` tags and moves your cursor within these tags after you type the `///` delimiter in the code editor. You can turn this feature on or off in the [Options dialog box](/visualstudio/ide/reference/options-text-editor-csharp-advanced). - -- `/** */` - - Multiline delimiters. - - There are some formatting rules to follow when you use the `/** */` delimiters: - - - On the line that contains the `/**` delimiter, if the remainder of the line is white space, the line is not processed for comments. If the first character after the `/**` delimiter is white space, that white space character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment. - - - On the line that contains the `*/` delimiter, if there is only white space up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment. - - - For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line. The pattern can consist of optional white space and an asterisk (`*`), followed by more optional white space. If the compiler finds a common pattern at the beginning of each line that does not begin with the `/**` delimiter or the `*/` delimiter, it ignores that pattern for each line. - - The following examples illustrate these rules. - - - The only part of the following comment that's processed is the line that begins with ``. The three tag formats produce the same comments. - - ```csharp - /** text */ - - /** - text - */ - - /** - * text - */ - ``` - - - The compiler identifies a common pattern of " \* " at the beginning of the second and third lines. The pattern is not included in the output. - - ```csharp - /** - * - * text */ - ``` - - - The compiler finds no common pattern in the following comment because the second character on the third line is not an asterisk. Therefore, all text on the second and third lines is processed as part of the comment. - - ```csharp - /** - * - text - */ - ``` - - - The compiler finds no pattern in the following comment for two reasons. First, the number of spaces before the asterisk is not consistent. Second, the fifth line begins with a tab, which does not match spaces. Therefore, all text from lines two through five is processed as part of the comment. - - - ```csharp - /** - * - * text - * text2 - * - */ - ``` - - -## See also - -- [C# programming guide](../index.md) -- [XML documentation comments](./index.md) -- [**DocumentationFile** (C# compiler options)](../../language-reference/compiler-options/output.md#documentationfile) diff --git a/docs/csharp/programming-guide/xmldoc/example.md b/docs/csharp/programming-guide/xmldoc/example.md deleted file mode 100644 index 7b2a60e65d564..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/example.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag lets you specify an example of how to use a method or other library member. -ms.date: 07/20/2015 -f1_keywords: - - "" - - "example" -helpviewer_keywords: - - " C# XML tag" - - "example C# XML tag" -ms.assetid: 32d6e73b-2554-4abb-83ee-a1e321334fd2 ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- `description` - - A description of the code sample. - -## Remarks - -The `` tag lets you specify an example of how to use a method or other library member. This commonly involves using the [\](./code.md) tag. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#3](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#3)] - -## See also - -- [C# Programming Guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/exception.md b/docs/csharp/programming-guide/xmldoc/exception.md deleted file mode 100644 index 518cf70387c88..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/exception.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag lets you specify which exceptions can be thrown, and can be applied to methods, properties, events, and indexers. -ms.date: 07/20/2015 -f1_keywords: - - "exception" - - "" -helpviewer_keywords: - - " C# XML tag" - - "exception C# XML tag" -ms.assetid: dd73aac5-3c74-4fcf-9498-f11bff3a2f3c ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- cref = " `member`" - - A reference to an exception that is available from the current compilation environment. The compiler checks that the given exception exists and translates `member` to the canonical element name in the output XML. `member` must appear within double quotation marks (" "). - - For more information on how to format `member` to reference a generic type, see [Processing the XML File](processing-the-xml-file.md). - -- `description` - - A description of the exception. - -## Remarks - -The `` tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -For more information about exception handling, see [Exceptions and Exception Handling](/dotnet/csharp/fundamentals/exceptions). - -## Example - -[!code-csharp[csProgGuideDocComments#4](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#4)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md b/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md deleted file mode 100644 index 63da9abd3ef8b..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: "How to use the XML documentation features - C# programming guide" -description: Learn how to use XML documentation features. See code examples and view additional available resources. -ms.date: 06/01/2018 -ms.topic: how-to -helpviewer_keywords: - - "XML documentation [C#]" - - "C# language, XML documentation features" -ms.assetid: 8f33917b-9577-4c9a-818a-640dbbb0b399 ---- -# How to use the XML documentation features - -The following sample provides a basic overview of a type that has been documented. - -## Example - -[!code-csharp[csProgGuideDocComments#15](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#15)] - -The example generates an *.xml* file with the following contents. - -```xml - - - - xmlsample - - - - - Class level summary documentation goes here. - - - Longer comments can be associated with a type or member through - the remarks tag. - - - - - Store for the Name property. - - - - - The class constructor. - - - - - Name property. - - - A value tag is used to describe the property value. - - - - - Description for SomeMethod. - - Parameter description for s goes here. - - You can use the cref attribute on any tag to reference a type or member - and the compiler will check that the reference exists. - - - - - Some other method. - - - Return values are described through the returns tag. - - - Notice the use of the cref attribute to reference a specific method. - - - - - The entry point for the application. - - A list of command line arguments. - - - - Documentation that describes the interface goes here. - - - Details about the interface go here. - - - - - Documentation that describes the method goes here. - - - Parameter n requires an integer argument. - - - The method returns an integer. - - - - -``` - -## Compiling the code - -To compile the example, enter the following command: - -`csc XMLsample.cs /doc:XMLsample.xml` - -This command creates the XML file *XMLsample.xml*, which you can view in your browser or by using the `TYPE` command. - -## Robust programming - -XML documentation starts with `///`. When you create a new project, the wizards put some starter `///` lines in for you. The processing of these comments has some restrictions: - -- The documentation must be well-formed XML. If the XML is not well-formed, a warning is generated and the documentation file will contain a comment that says that an error was encountered. - -- Developers are free to create their own set of tags. There is a [recommended set of tags](recommended-tags-for-documentation-comments.md). Some of the recommended tags have special meanings: - - - The `` tag is used to describe parameters. If used, the compiler verifies that the parameter exists and that all parameters are described in the documentation. If the verification fails, the compiler issues a warning. - - - The `cref` attribute can be attached to any tag to reference a code element. The compiler verifies that this code element exists. If the verification fails, the compiler issues a warning. The compiler respects any `using` statements when it looks for a type described in the `cref` attribute. - - - The `` tag is used by IntelliSense inside Visual Studio to display additional information about a type or member. - - > [!NOTE] - > The XML file does not provide full information about the type and members (for example, it does not contain any type information). To get full information about a type or member, use the documentation file together with reflection on the actual type or member. - -## See also - -- [C# programming guide](../index.md) -- [**DocumentationFile** (C# compiler options](../../language-reference/compiler-options/output.md#documentationfile) -- [XML documentation comments](./index.md) -- [DocFX documentation processor](https://dotnet.github.io/docfx/) -- [Sandcastle documentation processor](https://github.com/EWSoftware/SHFB) diff --git a/docs/csharp/programming-guide/xmldoc/include.md b/docs/csharp/programming-guide/xmldoc/include.md deleted file mode 100644 index 040b314b983d7..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/include.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag lets you refer to comments in another file that describe the types and members in your source code. -ms.date: 07/20/2015 -f1_keywords: - - "include" - - "" -helpviewer_keywords: - - " C# XML tag" - - "include C# XML tag" -ms.assetid: a8a70302-6196-4643-bd09-ef33f411f18f ---- -# \ (C# programming guide) - -## Syntax - -```xml - -``` - -## Parameters - -- `filename` - - The name of the XML file containing the documentation. The file name can be qualified with a path relative to the source code file. Enclose `filename` in single quotation marks (' '). - -- `tagpath` - - The path of the tags in `filename` that leads to the tag `name`. Enclose the path in single quotation marks (' '). - -- `name` - - The name specifier in the tag that precedes the comments; `name` will have an `id`. - -- `id` - - The ID for the tag that precedes the comments. Enclose the ID in double quotation marks (" "). - -## Remarks - -The `` tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out. - -The `` tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your `` use. - -## Example - -This is a multifile example. The following is the first file, which uses ``. - -[!code-csharp[csProgGuideDocComments#5](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#5)] - -The second file, *xml_include_tag.doc*, contains the following documentation comments. - -```xml - - - - -The summary for this type. - - - - - -The summary for this other type. - - - - -``` - -## Program output - -The following output is generated when you compile the Test and Test2 classes with the following command line: `-doc:DocFileName.xml.` In Visual Studio, you specify the XML doc comments option in the Build pane of the Project Designer. When the C# compiler sees the `` tag, it searches for documentation comments in *xml_include_tag.doc* instead of the current source file. The compiler then generates *DocFileName.xml*, and this is the file that is consumed by documentation tools such as [Sandcastle](https://github.com/EWSoftware/SHFB) to produce the final documentation. - -```xml - - - - xml_include_tag - - - - -The summary for this type. - - - - -The summary for this other type. - - - - -``` - -## See also - -- [C# Programming Guide](../index.md) -- [Recommended Tags for Documentation Comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/index.md b/docs/csharp/programming-guide/xmldoc/index.md deleted file mode 100644 index 4b182517920d8..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/index.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "XML documentation comments - C# programming guide" -description: Learn about XML documentation comments. You can create documentation for your code by including XML elements in special comment fields. -ms.date: 07/20/2015 -ms.topic: conceptual -f1_keywords: - - "cs.xml" -helpviewer_keywords: - - "XML [C#], code comments" - - "comments [C#], XML" - - "documentation comments [C#]" - - "C# source code files" - - "C# language, XML code comments" - - "XML documentation comments [C#]" -ms.assetid: 803b7f7b-7428-4725-b5db-9a6cff273199 ---- -# XML documentation comments (C# programming guide) - -In C#, you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer, for example. - -```csharp -/// -/// This class performs an important function. -/// -public class MyClass {} -``` - -When you compile with the [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) option, the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as [DocFX](https://dotnet.github.io/docfx/) or [Sandcastle](https://github.com/EWSoftware/SHFB). - -To refer to XML elements (for example, your function processes specific XML elements that you want to describe in an XML documentation comment), you can use the standard quoting mechanism (`<` and `>`). To refer to generic identifiers in code reference (`cref`) elements, you can use either the escape characters (for example, `cref="List<T>"`) or braces (`cref="List{T}"`). As a special case, the compiler parses the braces as angle brackets to make the documentation comment less cumbersome to author when referring to generic identifiers. - -> [!NOTE] -> The XML documentation comments are not metadata; they are not included in the compiled assembly and therefore they are not accessible through reflection. - -## In this section - -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) - -- [Processing the XML file](./processing-the-xml-file.md) - -- [Delimiters for documentation tags](./delimiters-for-documentation-tags.md) - -- [How to use the XML documentation features](./how-to-use-the-xml-documentation-features.md) - -## Related sections - -For more information, see: - -- [**DocumentationFile** (Process Documentation Comments)](../../language-reference/compiler-options/output.md#documentationfile) - -## C# language specification - -[!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] - -## See also - -- [C# Programming Guide](../index.md) diff --git a/docs/csharp/programming-guide/xmldoc/inheritdoc.md b/docs/csharp/programming-guide/xmldoc/inheritdoc.md deleted file mode 100644 index 77a9991ba5f2f..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/inheritdoc.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -description: "Learn more about: (C# Programming Guide)" -title: " - C# Programming Guide" -ms.date: 01/21/2020 -f1_keywords: - - "inheritdoc" - - "" -helpviewer_keywords: - - " C# XML tag" - - "inheritdoc C# XML tag" -ms.assetid: 46d329b1-5b84-4537-9e17-73ca97313e4e ---- -# \ (C# Programming Guide) - -## Syntax - -```xml - -``` - -## InheritDoc - -Inherit XML comments from base classes, interfaces, and similar methods. This eliminates unwanted copying and pasting of duplicate XML comments and automatically keeps XML comments synchronized. - -## Attributes - -#### cref - -Specify the member to inherit documentation from. -Already defined tags on the current member are not overridden by the inherited ones. - -#### path - -The XPath expression query that will result in a node set to show. -You can use this attribute to filter which tags to include or exclude from the inherited documentation. - -## Remarks - -Add your XML comments in base classes or interfaces and let InheritDoc copy the comments to implementing classes. - -Add your XML comments to your synchronous methods and let InheritDoc copy the comments to your asynchronous versions of the same methods. - -If you want to copy the comments from a specific member you can use the `cref` attribute to specify the member. - -## Examples - -[!code-csharp[csProgGuideDocComments#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#16)] - -[!code-csharp[csProgGuideDocComments#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#17)] -[!code-csharp[csProgGuideDocComments#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#18)] -[!code-csharp[csProgGuideDocComments#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#19)] - -## See also - -- [C# Programming Guide](../index.md) -- [Recommended Tags for Documentation Comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/list.md b/docs/csharp/programming-guide/xmldoc/list.md deleted file mode 100644 index 475774e49d897..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/list.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag is used to create tables and definition, bulleted, or numbered lists by using 'item' blocks. -ms.date: 07/20/2015 -f1_keywords: - - "list" - - "" -helpviewer_keywords: - - "list C# XML tag" - - "listheader C# XML tag" - - " C# XML tag" - - "item C# XML tag" - - " C# XML tag" - - " C# XML tag" -ms.assetid: c9620b1b-c2e6-43f1-ab88-8ab47308ffec ---- -# \ (C# programming guide) - -## Syntax - -```xml - - - term - description - - - term - description - - -``` - -## Parameters - -- `term` - - A term to define, which will be defined in `description`. - -- `description` - - Either an item in a bullet or numbered list or the definition of a `term`. - -## Remarks - -The `` block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading. - -Each item in the list is specified with an `` block. When creating a definition list, you will need to specify both `term` and `description`. However, for a table, bulleted list, or numbered list, you only need to supply an entry for `description`. - -A list or table can have as many `` blocks as needed. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#6](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#6)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/para.md b/docs/csharp/programming-guide/xmldoc/para.md deleted file mode 100644 index 3e0695b733167..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/para.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag lets you add structure to the text in another tag, such as , , or . -ms.date: 07/20/2015 -f1_keywords: - - "" - - "para" -helpviewer_keywords: - - " C# XML tag" - - "para C# XML tag" -ms.assetid: c74b8705-29df-40b1-bff5-237492b0e978 ---- -# \ (C# programming guide) - -## Syntax - -```xml -content -``` - -## Parameters - -- `content` - - The text of the paragraph. - -## Remarks - -The `` tag is for use inside a tag, such as [\](./summary.md), [\](./remarks.md), or [\](./returns.md), and lets you add structure to the text. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -See [\](./summary.md) for an example of using ``. - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/param.md b/docs/csharp/programming-guide/xmldoc/param.md deleted file mode 100644 index 4acf795af57d7..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/param.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag is used in the comment for a method declaration to describe one of the parameters for the method. -ms.date: 07/20/2015 -f1_keywords: - - "param" - - "" -helpviewer_keywords: - - " C# XML tag" - - "param C# XML tag" -ms.assetid: 46d329b1-5b84-4537-9e17-73ca97313e4e ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- `name` - - The name of a method parameter. Enclose the name in double quotation marks (" "). - -- `description` - - A description for the parameter. - -## Remarks - -The `` tag should be used in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple `` tags. - -The text for the `` tag is displayed in IntelliSense, the Object Browser, and the Code Comment Web Report. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#1](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#1)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/paramref.md b/docs/csharp/programming-guide/xmldoc/paramref.md deleted file mode 100644 index 53949410a0a74..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/paramref.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag gives you a way to indicate that a word in the code is a parameter. -ms.date: 07/20/2015 -f1_keywords: - - "paramref" - - "" -helpviewer_keywords: - - " C# XML tag" - - "paramref C# XML tag" -ms.assetid: 756c24c1-f591-40e8-a838-559761539b0b ---- -# \ (C# programming guide) - -## Syntax - -```xml - -``` - -## Parameters - -- `name` - - The name of the parameter to refer to. Enclose the name in double quotation marks (" "). - -## Remarks - -The `` tag gives you a way to indicate that a word in the code comments, for example in a `` or `` block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#7](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#7)] - -## See also - -- [C# Programming Guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/permission.md b/docs/csharp/programming-guide/xmldoc/permission.md deleted file mode 100644 index 5baf1011935f9..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/permission.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag lets you document the access of a member, while the PermissionSet class lets you specify access to a member. -ms.date: 07/20/2015 -f1_keywords: - - "permission" - - "" -helpviewer_keywords: - - " C# XML tag" - - "permission C# XML tag" -ms.assetid: 769e93fe-8404-443f-bf99-577aa42b6a49 ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- cref = " `member`" - - A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and translates `member` to the canonical element name in the output XML. *member* must appear within double quotation marks (" "). - - For information on how to create a cref reference to a generic type, see [cref attribute](./cref-attribute.md). - -- `description` - - A description of the access to the member. - -## Remarks - -The `` tag lets you document the access of a member. The class lets you specify access to a member. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#8](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#8)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md b/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md deleted file mode 100644 index 8eecb1ec9c0bb..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Processing the XML file - C# programming guide" -description: Learn about processing the XML file in C# programming. See code examples and view additional available resources. -ms.date: 07/20/2015 -ms.topic: conceptual -helpviewer_keywords: - - "XML processing [C#]" - - "XML [C#], processing" -ms.assetid: 60c71193-9dac-4cd3-98c5-100bd0edcc42 ---- -# Process the XML file (C# programming guide) - -The compiler generates an ID string for each construct in your code that's tagged to generate documentation. (For information about how to tag your code, see [Recommended Tags for Documentation Comments](./recommended-tags-for-documentation-comments.md).) The ID string uniquely identifies the construct. Programs that process the XML file can use the ID string to identify the corresponding .NET metadata or reflection item that the documentation applies to. - -## ID strings - -The XML file is not a hierarchical representation of your code. It's a flat list that has a generated ID for each element. - -The compiler observes the following rules when it generates the ID strings: - -- No white space is in the string. - -- The first part of the string identifies the kind of member using a single character followed by a colon. The following member types are used: - - |Character|Member type|Notes| - |---------------|-----------------|-| - |N|namespace|You cannot add documentation comments to a namespace, but you can make cref references to them, where supported.| - |T|type|A type can be a class, interface, struct, enum, or delegate.| - |F|field| - |P|property|Includes indexers or other indexed properties.| - |M|method|Includes special methods, such as constructors and operators.| - |E|event| - |!|error string|The rest of the string provides information about the error. The C# compiler generates error information for links that cannot be resolved.| - -- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type(s), and namespace are separated by periods. If the name of the item itself has periods, they are replaced by the hash-sign ('#'). It's assumed that no item has a hash-sign directly in its name. For example, the fully qualified name of the String constructor is "System.String.#ctor". - -- For properties and methods, the parameter list enclosed in parentheses follows. If there are no parameters, no parentheses are present. The parameters are separated by commas. The encoding of each parameter follows directly how it's encoded in a .NET signature: - - - Base types. Regular types (ELEMENT_TYPE_CLASS or ELEMENT_TYPE_VALUETYPE) are represented as the fully qualified name of the type. - - - Intrinsic types (for example, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF, and ELEMENT_TYPE_VOID) are represented as the fully qualified name of the corresponding full type. For example, System.Int32 or System.TypedReference. - - - ELEMENT_TYPE_PTR is represented as a '\*' following the modified type. - - - ELEMENT_TYPE_BYREF is represented as a '\@' following the modified type. - - - ELEMENT_TYPE_PINNED is represented as a '^' following the modified type. The C# compiler never generates this. - - - ELEMENT_TYPE_CMOD_REQ is represented as a '|' and the fully qualified name of the modifier class, following the modified type. The C# compiler never generates this. - - - ELEMENT_TYPE_CMOD_OPT is represented as a '!' and the fully qualified name of the modifier class, following the modified type. - - - ELEMENT_TYPE_SZARRAY is represented as "[]" following the element type of the array. - - - ELEMENT_TYPE_GENERICARRAY is represented as "[?]" following the element type of the array. The C# compiler never generates this. - - - ELEMENT_TYPE_ARRAY is represented as [*lowerbound*:`size`,*lowerbound*:`size`] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size is not specified, it's omitted. If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. For example, a 2-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:]. - - - ELEMENT_TYPE_FNPTR is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The C# compiler never generates this. - - The following signature components aren't represented because they aren't used to differentiate overloaded methods: - - - calling convention - - - return type - - - ELEMENT_TYPE_SENTINEL - -- For conversion operators only (`op_Implicit` and `op_Explicit`), the return value of the method is encoded as a '~' followed by the return type. - -- For generic types, the name of the type is followed by a backtick and then a number that indicates the number of generic type parameters. For example: - - ```` is the tag for a type that is defined as `public class SampleClass`. - - For methods that take generic types as parameters, the generic type parameters are specified as numbers prefaced with backticks (for example \`0,\`1). Each number represents a zero-based array notation for the type's generic parameters. - -## Examples - -The following examples show how the ID strings for a class and its members are generated: - -[!code-csharp[csProgGuidePointers#21](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuidePointers/CS/Pointers.cs#21)] - -## See also - -- [C# programming guide](../index.md) -- [**DocumentationFile** (C# compiler options)](../../language-reference/compiler-options/output.md#documentationfile) -- [XML documentation comments](./index.md) diff --git a/docs/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments.md b/docs/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments.md deleted file mode 100644 index 9f7a5bf7efd19..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Recommended tags for documentation comments - C# programming guide" -description: Learn about the recommended tags for documentation comments. See a list of recommended tags and view additional available resources. -ms.date: 01/21/2020 -ms.topic: conceptual -helpviewer_keywords: - - "XML [C#], tags" - - "XML documentation [C#], tags" -ms.assetid: 6e98f7a9-38f4-4d74-b644-1ff1b23320fd ---- -# Recommended tags for documentation comments (C# programming guide) - -The C# compiler processes documentation comments in your code and formats them as XML in a file whose name you specify in the **/doc** command-line option. To create the final documentation based on the compiler-generated file, you can create a custom tool, or use a tool such as [DocFX](https://dotnet.github.io/docfx/) or [Sandcastle](https://github.com/EWSoftware/SHFB). - -Tags are processed on code constructs such as types and type members. - -> [!NOTE] -> Documentation comments cannot be applied to a namespace. - -The compiler will process any tag that is valid XML. The following tags provide generally used functionality in user documentation. - -## Tags - -:::row::: - :::column::: - [\](./code-inline.md) - [\](./code.md) - [\](./example.md) - [\](./exception.md)\* - [\](./include.md)\* - [\](./inheritdoc.md) - :::column-end::: - :::column::: - [\](./list.md) - [\](./para.md) - [\](./param.md)* - [\](./paramref.md) - [\](./permission.md)\* - [\](./remarks.md) - :::column-end::: - :::column::: - [\](./returns.md) - [\](./see.md)\* - [\](./seealso.md)\* - [\](./summary.md) - [\](./typeparam.md)\* - [\](./typeparamref.md) - [\](./value.md) - :::column-end::: -:::row-end::: - -(\* denotes that the compiler verifies syntax.) - -If you want angle brackets to appear in the text of a documentation comment, use the HTML encoding of `<` and `>` which is `<` and `>` respectively. This encoding is shown in the following example. - -```csharp -/// -/// This property always returns a value < 1. -/// -``` - -## See also - -- [C# programming guide](../index.md) -- [**DocumentationFile** (C# compiler options)](../../language-reference/compiler-options/output.md#documentationfile) -- [XML documentation comments](./index.md) diff --git a/docs/csharp/programming-guide/xmldoc/remarks.md b/docs/csharp/programming-guide/xmldoc/remarks.md deleted file mode 100644 index 79cd00fab2497..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/remarks.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag is used to add information about a type, supplementing the information specified with . -ms.date: 07/20/2015 -f1_keywords: - - "remarks" - - "" -helpviewer_keywords: - - "remarks C# XML tag" - - " C# XML tag" -ms.assetid: f8641391-31f3-4735-af7a-c502a5b6a251 ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- `Description` - - A description of the member. - -## Remarks - -The `` tag is used to add information about a type, supplementing the information specified with [\](./summary.md). This information is displayed in the Object Browser window. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#9](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#9)] - -## See also - -- [C# Programming Guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/returns.md b/docs/csharp/programming-guide/xmldoc/returns.md deleted file mode 100644 index b804a16e3f527..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/returns.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag is used in the comment for a method declaration to describe the return value. -ms.date: 07/20/2015 -f1_keywords: - - "returns" - - "" -helpviewer_keywords: - - " C# XML tag" - - "returns C# XML tag" -ms.assetid: bb2d9958-62fc-47c7-9511-6311171f119f ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- `description` - - A description of the return value. - -## Remarks - -The `` tag should be used in the comment for a method declaration to describe the return value. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#10](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#10)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/see.md b/docs/csharp/programming-guide/xmldoc/see.md deleted file mode 100644 index 8700ab81e927a..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/see.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag lets you specify a link from within text, for example by using a cref attribute. -ms.date: 07/20/2015 -f1_keywords: - - "" - - "see" -helpviewer_keywords: - - "cref [C#], tag" - - " C# XML tag" - - "cross-references [C#]" - - "see C# XML tag" -ms.assetid: 0200de01-7e2f-45c4-9094-829d61236383 ---- -# \ (C# programming guide) - -## Syntax - -```csharp -/// -// or -/// Link Text -// or -/// -``` - -## Parameters - -- `cref="member"` - - A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes `member` to the element name in the output XML. Place *member* within double quotation marks (" "). - -- `href="link"` - - A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. - -- `langword="keyword"` - - A language keyword, such as `true`. - -## Remarks - -The `` tag lets you specify a link from within text. Use [\](./seealso.md) to indicate that text should be placed in a See Also section. Use the [cref Attribute](./cref-attribute.md) to create internal hyperlinks to documentation pages for code elements. Also, ``href`` is a valid Attribute that will function as a hyperlink. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -The following example shows a `` tag within a summary section. - -[!code-csharp[csProgGuideDocComments#12](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#12)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/seealso.md b/docs/csharp/programming-guide/xmldoc/seealso.md deleted file mode 100644 index ac250c373d706..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/seealso.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn how to use the XML tag. This tag lets you specify the text that you might want to appear in a 'See Also' section. -ms.date: 07/20/2015 -f1_keywords: - - "cref" - - "" - - "seealso" -helpviewer_keywords: - - "cref [C#], see also" - - "seealso C# XML tag" - - "cref [C#]" - - "cross-references [C#], tags" - - " C# XML tag" -ms.assetid: 8e157f3f-f220-4fcf-9010-88905b080b18 ---- -# \ (C# programming guide) - -## Syntax - -```csharp -/// -// or -/// Link Text -``` - -## Parameters - -- `cref="member"` - - A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes `member` to the element name in the output XML.`member` must appear within double quotation marks (" "). - - For information on how to create a cref reference to a generic type, see [cref attribute](./cref-attribute.md). - -- `href="link"` - - A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. - -## Remarks - -The `` tag lets you specify the text that you might want to appear in a See Also section. Use [\](./see.md) to specify a link from within text. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -See [\](./summary.md) for an example of using \. - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/summary.md b/docs/csharp/programming-guide/xmldoc/summary.md deleted file mode 100644 index 97d4e4c093020..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/summary.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag that is used to describe a type or a type member. See code examples and view additional available resources. -ms.date: 07/20/2015 -f1_keywords: - - "" - - "summary" -helpviewer_keywords: - - " C# XML tag" - - "summary C# XML tag" -ms.assetid: b4c43d92-2067-4eac-a59a-d32f5248c08b ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- `description` - - A summary of the object. - -## Remarks - -The `` tag should be used to describe a type or a type member. Use [\](./remarks.md) to add supplemental information to a type description. Use the [cref Attribute](./cref-attribute.md) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. - -The text for the `` tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser Window. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. To create the final documentation based on the compiler-generated file, you can create a custom tool, or use a tool such as [DocFX](https://dotnet.github.io/docfx/) or [Sandcastle](https://github.com/EWSoftware/SHFB). - -## Example - -[!code-csharp[csProgGuideDocComments#12](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#12)] - -The previous example produces the following XML file. - -```xml - - - - YourNamespace - - - - text for class TestClass - - - DoWork is a method in the TestClass class. - Here's how you could make a second paragraph in a description. for information about output statements. - - - - - text for Main - - - -``` - -## cref example - -The following example shows how to make a `cref` reference to a generic type. - -[!code-csharp[csProgGuideDocComments#11](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#11)] - -The previous example produces the following XML file. - -```xml - - - - CRefTest - - - - - - - - - - - - - - - - - -``` - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/typeparam.md b/docs/csharp/programming-guide/xmldoc/typeparam.md deleted file mode 100644 index 49be312d75ea2..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/typeparam.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag is used in the comment for a generic type or method declaration to describe a type parameter. -ms.date: 07/20/2015 -f1_keywords: - - "typeparam" -helpviewer_keywords: - - " C# XML tag" - - "typeparam C# XML tag" -ms.assetid: 9b99d400-e911-4e55-99c6-64367c96aa4f ---- -# \ (C# programming guide) - -## Syntax - -```xml -description -``` - -## Parameters - -- `name` - - The name of the type parameter. Enclose the name in double quotation marks (" "). - -- `description` - - A description for the type parameter. - -## Remarks - -The `` tag should be used in the comment for a generic type or method declaration to describe a type parameter. Add a tag for each type parameter of the generic type or method. - -For more information, see [Generics](../../fundamentals/types/generics.md). - -The text for the `` tag will be displayed in IntelliSense, the [Object Browser Window](/visualstudio/ide/viewing-the-structure-of-code#BKMK_ObjectBrowser) code comment web report. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#13](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#13)] - -## See also - -- [C# reference](../../language-reference/index.md) -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/typeparamref.md b/docs/csharp/programming-guide/xmldoc/typeparamref.md deleted file mode 100644 index 76fbbb56311b0..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/typeparamref.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag enables consumers of the documentation file to format the word in some distinct way, for example in italics. -ms.date: 07/20/2015 -f1_keywords: - - "typeparamref" -helpviewer_keywords: - - "typeparamref C# XML tag" - - " C# XML tag" -ms.assetid: 6d8ffc58-12c5-4688-8db6-833a7ded5886 ---- -# \ (C# programming guide) - -## Syntax - -```xml - -``` - -## Parameters - -- `name` - - The name of the type parameter. Enclose the name in double quotation marks (" "). - -## Remarks - -For more information on type parameters in generic types and methods, see [Generics](../../fundamentals/types/generics.md). - -Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#13](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#13)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/programming-guide/xmldoc/value.md b/docs/csharp/programming-guide/xmldoc/value.md deleted file mode 100644 index 18f28c69865aa..0000000000000 --- a/docs/csharp/programming-guide/xmldoc/value.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: " - C# programming guide" -description: Learn about the XML tag. This tag allows you to describe the value that a property represents. -ms.date: 07/20/2015 -f1_keywords: - - "" -helpviewer_keywords: - - " C# XML tag" - - "value C# XML tag" -ms.assetid: 08dbadaf-9ab6-43d9-9493-98e43bed199a ---- -# \ (C# programming guide) - -## Syntax - -```xml -property-description -``` - -## Parameters - -- `property-description` - - A description for the property. - -## Remarks - -The `` tag lets you describe the value that a property represents. When you add a property via code wizard in the Visual Studio .NET development environment, it adds a [\](./summary.md) tag for the new property. You should then manually add a `` tag to describe the value that the property represents. - -Compile with [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) to process documentation comments to a file. - -## Example - -[!code-csharp[csProgGuideDocComments#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#14)] - -## See also - -- [C# programming guide](../index.md) -- [Recommended tags for documentation comments](./recommended-tags-for-documentation-comments.md) diff --git a/docs/csharp/toc.yml b/docs/csharp/toc.yml index 8162ed8f5c8a1..146c165ab2cc8 100644 --- a/docs/csharp/toc.yml +++ b/docs/csharp/toc.yml @@ -296,8 +296,6 @@ items: href: expression-trees-summary.md - name: Native interoperability href: programming-guide/interop/index.md - - name: Documenting your code - href: codedoc.md - name: Versioning href: versioning.md - name: How-to C# articles @@ -824,61 +822,6 @@ items: href: programming-guide/namespaces/using-namespaces.md - name: "How to use the My namespace" href: programming-guide/namespaces/how-to-use-the-my-namespace.md - - name: XML documentation comments - items: - - name: Overview - displayName: xml documentation comments - href: programming-guide/xmldoc/index.md - - name: Recommended tags for documentation comments - href: programming-guide/xmldoc/recommended-tags-for-documentation-comments.md - - name: Processing the XML file - href: programming-guide/xmldoc/processing-the-xml-file.md - - name: Delimiters for documentation tags - href: programming-guide/xmldoc/delimiters-for-documentation-tags.md - - name: How to use the XML documentation features - href: programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md - - name: Documentation tag reference - items: - - name: - href: programming-guide/xmldoc/code-inline.md - - name: - href: programming-guide/xmldoc/code.md - - name: cref attribute - href: programming-guide/xmldoc/cref-attribute.md - - name: - href: programming-guide/xmldoc/example.md - - name: - href: programming-guide/xmldoc/exception.md - - name: - href: programming-guide/xmldoc/include.md - - name: - href: programming-guide/xmldoc/inheritdoc.md - - name: - href: programming-guide/xmldoc/list.md - - name: - href: programming-guide/xmldoc/para.md - - name: - href: programming-guide/xmldoc/param.md - - name: - href: programming-guide/xmldoc/paramref.md - - name: - href: programming-guide/xmldoc/permission.md - - name: - href: programming-guide/xmldoc/remarks.md - - name: - href: programming-guide/xmldoc/returns.md - - name: - href: programming-guide/xmldoc/see.md - - name: - href: programming-guide/xmldoc/seealso.md - - name: - href: programming-guide/xmldoc/summary.md - - name: - href: programming-guide/xmldoc/typeparam.md - - name: - href: programming-guide/xmldoc/typeparamref.md - - name: - href: programming-guide/xmldoc/value.md - name: File System and the Registry items: - name: Overview @@ -1355,6 +1298,14 @@ items: - name: Advanced options displayName: MainEntryPoint, StartupObject, main, PdbFile, pdb, PathMap, pathmap, ApplicationConfiguration, appconfig, AdditionalLibPaths, lib, GenerateFullPaths, fullpath, PreferredUILang, preferreduilang, BaseAddress, baseaddress, ChecksumAlgorithm, checksumalgorithm, CodePage, codepage, Utf8Output, utf8output, FileAlignment, filealign, ErrorEndLocation, errorendlocation, NoStandardLib, nostdlib, SubsystemVersion, subsystemversion, ModuleAssemblyName, moduleassemblyname href: language-reference/compiler-options/advanced.md + - name: XML documentation comments + items: + - name: Generate API documentation + href: language-reference/xmldoc/index.md + - name: Recommended tags + href: language-reference/xmldoc/recommended-tags.md + - name: Examples + href: language-reference/xmldoc/examples.md - name: Compiler messages href: language-reference/compiler-messages/index.md - name: Specifications diff --git a/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md b/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md index 8dccebb45e5cf..25093b41d4cd3 100644 --- a/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md +++ b/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md @@ -77,5 +77,5 @@ This code example requires the `FullTrust` permission set to execute successfull ## See also - [Document your code with XML (Visual Basic)](../../visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md) -- [XML documentation comments](../../csharp/programming-guide/xmldoc/index.md) +- [XML documentation comments](/dotnet/csharp/language-reference/xmldoc) - [XML documentation (C++)](/cpp/ide/xml-documentation-visual-cpp) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 6bd5cbc207e9b..bbf53dd1324c8 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -136,6 +136,6 @@ Documenting code is recommended for many reasons. What follows are some best pra ## See also -- [C# XML Documentation Comments (C# Programming Guide)](../../csharp/programming-guide/xmldoc/index.md). +- [C# XML Documentation Comments (C# Programming Guide)](/dotnet/csharp/language-reference/xmldoc). - [F# Language Reference](index.md) - [Compiler Options](compiler-options.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1010.md b/docs/fundamentals/code-analysis/quality-rules/ca1010.md index 3539640f49297..7b02ab482a6cd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1010.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1010.md @@ -68,7 +68,7 @@ You can configure the list of interface names (separated by `|`) with their requ Allowed interface formats: - Interface name only (includes all interfaces with the name, regardless of the containing type or namespace). -- Fully qualified names in the symbol's [documentation ID format](../../../csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings) with an optional `T:` prefix. +- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings) with an optional `T:` prefix. Examples: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1031.md b/docs/fundamentals/code-analysis/quality-rules/ca1031.md index fbde59d20b19c..6275add8cb87f 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1031.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1031.md @@ -63,7 +63,7 @@ dotnet_code_quality.CA1031.disallowed_symbol_names = NullReferenceException Allowed type name formats in the option value (separated by `|`): - Type name only (includes all symbols with the name, regardless of the containing type or namespace) -- Fully qualified names in the symbol's [documentation ID format](../../../csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings) with a `T:` prefix. +- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings) with a `T:` prefix. Examples: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1062.md b/docs/fundamentals/code-analysis/quality-rules/ca1062.md index ee0a8884479db..bcffdb9693eb6 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1062.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1062.md @@ -78,7 +78,7 @@ dotnet_code_quality.CA1062.null_check_validation_methods = Validate Allowed method name formats in the option value (separated by `|`): - Method name only (includes all methods with the name, regardless of the containing type or namespace). -- Fully qualified names in the symbol's [documentation ID format](../../../csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings), with an optional `M:` prefix. +- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings), with an optional `M:` prefix. Examples: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1200.md b/docs/fundamentals/code-analysis/quality-rules/ca1200.md index 343ff76831367..12137c9c893af 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1200.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1200.md @@ -24,11 +24,11 @@ dev_langs: ## Cause -The [cref](../../../csharp/programming-guide/xmldoc/cref-attribute.md) tag in an XML documentation comment uses a [prefix](../../../csharp/programming-guide/xmldoc/processing-the-xml-file.md). +The [cref](../../../csharp/language-reference/xmldoc/recommended-tags.md) tag in an XML documentation comment uses a [prefix](/dotnet/csharp/language-reference/xmldoc#id-strings). ## Rule description -The [cref](../../../csharp/programming-guide/xmldoc/cref-attribute.md) attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using `cref` tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. It is recommended that you use the full syntax without prefixes to reference symbol names in cref tags. +The [cref](../../../csharp/language-reference/xmldoc/recommended-tags.md) attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using `cref` tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. It is recommended that you use the full syntax without prefixes to reference symbol names in cref tags. ## How to fix violations @@ -62,4 +62,4 @@ It's safe to suppress this warning if the code reference must use a prefix becau ## See also -- [Documenting your code with XML comments](../../../csharp/codedoc.md) +- [Documenting your code with XML comments](../../../csharp/language-reference/xmldoc/recommended-tags.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1710.md b/docs/fundamentals/code-analysis/quality-rules/ca1710.md index fa52f757cba37..1c43dab665555 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1710.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1710.md @@ -115,7 +115,7 @@ dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix] Separate multiple values with a `|` character. Types can be specified in either of the following formats: - Type name only (includes all types with the name, regardless of the containing type or namespace). -- Fully qualified names in the symbol's [documentation ID format](../../../csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings) with an optional `T:` prefix. +- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings) with an optional `T:` prefix. Examples: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2241.md b/docs/fundamentals/code-analysis/quality-rules/ca2241.md index a91b12d1de6b2..54fa09f5a1638 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2241.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2241.md @@ -60,7 +60,7 @@ dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat Allowed method name formats in the option value (separated by `|`): - Method name only (includes all methods with the name, regardless of the containing type or namespace) -- Fully qualified names in the symbol's [documentation ID format](../../../csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings), with an optional `M:` prefix. +- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings), with an optional `M:` prefix. Examples: diff --git a/docs/fundamentals/code-analysis/quality-rules/documentation-warnings.md b/docs/fundamentals/code-analysis/quality-rules/documentation-warnings.md index 363d0f20f1c05..16f1e9528bec5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/documentation-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/documentation-warnings.md @@ -14,10 +14,10 @@ ms.author: mavasani --- # Documentation rules -Documentation rules support writing well-documented libraries through the correct use of [XML documentation comments](../../../csharp/codedoc.md) for externally visible APIs. +Documentation rules support writing well-documented libraries through the correct use of [XML documentation comments](../../../csharp/language-reference/xmldoc/recommended-tags.md) for externally visible APIs. ## In this section | Rule | Description | | - | - | -| [CA1200: Avoid using cref tags with a prefix](ca1200.md) | The [cref](../../../csharp/programming-guide/xmldoc/cref-attribute.md) attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using `cref` tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. | +| [CA1200: Avoid using cref tags with a prefix](ca1200.md) | The [cref](../../../csharp/language-reference/xmldoc/recommended-tags.md) attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using `cref` tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. | diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md index 38794fd791887..0f5f22cfa7049 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/docs/fundamentals/code-analysis/quality-rules/index.md @@ -66,7 +66,7 @@ The following table lists code quality analysis rules. > | [CA1068: CancellationToken parameters must come last](ca1068.md) | A method has a CancellationToken parameter that is not the last parameter. | > | [CA1069: Enums should not have duplicate values](ca1069.md) | An enumeration has multiple members which are explicitly assigned the same constant value. | > | [CA1070: Do not declare event fields as virtual](ca1070.md) | A [field-like event](../../../csharp/event-pattern.md#defining-and-raising-field-like-events) was declared as virtual. | -> | [CA1200: Avoid using cref tags with a prefix](ca1200.md) | The [cref](../../../csharp/programming-guide/xmldoc/cref-attribute.md) attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using `cref` tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. | +> | [CA1200: Avoid using cref tags with a prefix](ca1200.md) | The [cref](../../../csharp/language-reference/xmldoc/recommended-tags.md) attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using `cref` tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. | > | [CA1303: Do not pass literals as localized parameters](ca1303.md) | An externally visible method passes a string literal as a parameter to a .NET constructor or method, and that string should be localizable. | > | [CA1304: Specify CultureInfo](ca1304.md) | A method or constructor calls a member that has an overload that accepts a System.Globalization.CultureInfo parameter, and the method or constructor does not call the overload that takes the CultureInfo parameter. When a CultureInfo or System.IFormatProvider object is not supplied, the default value that is supplied by the overloaded member might not have the effect that you want in all locales. | > | [CA1305: Specify IFormatProvider](ca1305.md) | A method or constructor calls one or more members that have overloads that accept a System.IFormatProvider parameter, and the method or constructor does not call the overload that takes the IFormatProvider parameter. When a System.Globalization.CultureInfo or IFormatProvider object is not supplied, the default value that is supplied by the overloaded member might not have the effect that you want in all locales. | diff --git a/docs/fundamentals/code-analysis/style-rules/ide0005.md b/docs/fundamentals/code-analysis/style-rules/ide0005.md index 564f753a216d8..5ea910afd2853 100644 --- a/docs/fundamentals/code-analysis/style-rules/ide0005.md +++ b/docs/fundamentals/code-analysis/style-rules/ide0005.md @@ -34,7 +34,7 @@ This rule flags the following unnecessary constructs: These unnecessary constructs can be removed without changing the semantics of the code. This rule has no associated code style option. > [!NOTE] -> To enable this [rule on build](../overview.md#code-style-analysis), you need to enable [XML documentation comments](../../../csharp/codedoc.md) for the project. See [this issue](https://github.com/dotnet/roslyn/issues/41640) for more details. +> To enable this [rule on build](../overview.md#code-style-analysis), you need to enable [XML documentation comments](../../../csharp/language-reference/xmldoc/recommended-tags.md) for the project. See [this issue](https://github.com/dotnet/roslyn/issues/41640) for more details. ## Example diff --git a/includes/code-analysis/excluded-symbol-names.md b/includes/code-analysis/excluded-symbol-names.md index 04d2aa6dbb0dc..17d44f2a91172 100644 --- a/includes/code-analysis/excluded-symbol-names.md +++ b/includes/code-analysis/excluded-symbol-names.md @@ -9,7 +9,7 @@ dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Allowed symbol name formats in the option value (separated by `|`): - Symbol name only (includes all symbols with the name, regardless of the containing type or namespace). -- Fully qualified names in the symbol's [documentation ID format](../../docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings). Each symbol name requires a symbol-kind prefix, such as `M:` for methods, `T:` for types, and `N:` for namespaces. +- Fully qualified names in the symbol's [documentation ID format](../../docs/csharp/language-reference/xmldoc/index.md#id-strings). Each symbol name requires a symbol-kind prefix, such as `M:` for methods, `T:` for types, and `N:` for namespaces. - `.ctor` for constructors and `.cctor` for static constructors. Examples: diff --git a/includes/code-analysis/excluded-type-names-with-derived-types.md b/includes/code-analysis/excluded-type-names-with-derived-types.md index 5c35816c148f8..8269a1944e552 100644 --- a/includes/code-analysis/excluded-type-names-with-derived-types.md +++ b/includes/code-analysis/excluded-type-names-with-derived-types.md @@ -9,7 +9,7 @@ dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Allowed symbol name formats in the option value (separated by `|`): - Type name only (includes all types with the name, regardless of the containing type or namespace). -- Fully qualified names in the symbol's [documentation ID format](../../docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md#id-strings), with an optional `T:` prefix. +- Fully qualified names in the symbol's [documentation ID format](../../docs/csharp/language-reference/xmldoc/index.md#id-strings), with an optional `T:` prefix. Examples: diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs deleted file mode 100644 index e979d8cb7b8b1..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs +++ /dev/null @@ -1,636 +0,0 @@ -//----------------------------------------------------------------------------- -namespace Wrap1 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - // Single parameter. - /// Used to indicate status. - public static void DoWork(int Int1) - { - } - - // Multiple parameters. - /// Used to indicate status. - /// Used to specify context. - public static void DoWork(int Int1, float Float1) - { - } - - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap2 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - /// DoWork is a method in the TestClass class. - /// - public static void DoWork(int Int1) - { - } - - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -// -// Save this file as CRefTest.cs -// Compile with: csc CRefTest.cs -doc:Results.xml - -namespace TestNamespace -{ - /// - /// TestClass contains several cref examples. - /// - public class TestClass - { - /// - /// This sample shows how to specify the constructor as a cref attribute. - /// - public TestClass() - { } - - /// - /// This sample shows how to specify the constructor as a cref attribute. - /// - public TestClass(int value) - { } - - /// - /// The GetZero method. - /// - /// - /// This sample shows how to call the method. - /// - /// class TestClass - /// { - /// static int Main() - /// { - /// return GetZero(); - /// } - /// } - /// - /// - public static int GetZero() - { - return 0; - } - - /// - /// The GetGenericValue method. - /// - /// - /// This sample shows how to specify the method as a cref attribute. - /// - - public static T GetGenericValue(T para) - { - return para; - } - } - - /// - /// GenericClass. - /// - /// - /// This example shows how to specify the type as a cref attribute. - /// - class GenericClass - { - // Fields and members. - } - - class Program - { - static int Main() - { - return TestClass.GetZero(); - } - } -} -// - -namespace Wrap3 -{ - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - /// - /// The GetZero method. - /// - /// This sample shows how to call the method. - /// - /// class TestClass - /// { - /// static int Main() - /// { - /// return GetZero(); - /// } - /// } - /// - /// - public static int GetZero() - { - return 0; - } - - /// text for Main - static void Main() - { - } - } -} - -//----------------------------------------------------------------------------- -namespace Wrap4 -{ - // - // compile with: -doc:DocFileName.xml - - /// Comment for class - public class EClass : System.Exception - { - // class definition... - } - - /// Comment for class - class TestClass - { - /// Thrown when... - public void DoSomething() - { - try - { - } - catch (EClass) - { - } - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap5 -{ - // - // compile with: -doc:DocFileName.xml - - /// - class Test - { - static void Main() - { - } - } - - /// - class Test2 - { - public void Test() - { - } - } - // - // Following line is a trick to try to fix a problem in the msdn build. - /**/ -} - -//----------------------------------------------------------------------------- -namespace Wrap6 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - /// Here is an example of a bulleted list: - /// - /// - /// Item 1. - /// - /// - /// Item 2. - /// - /// - /// - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap7 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - /// DoWork is a method in the TestClass class. - /// The parameter takes a number. - /// - public static void DoWork(int int1) - { - } - - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap8 -{ - // - // compile with: -doc:DocFileName.xml - - class TestClass - { - /// Everyone can access this method. - public static void Test() - { - } - - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap9 -{ - // - // compile with: -doc:DocFileName.xml - - /// - /// You may have some primary information about this class. - /// - /// - /// You may have some additional information about this class. - /// - public class TestClass - { - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap10 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - /// Returns zero. - public static int GetZero() - { - return 0; - } - - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap11 -{ - // - // compile with: -doc:DocFileName.xml - - // the following cref shows how to specify the reference, such that, - // the compiler will resolve the reference - /// - /// - class A { } - - // the following cref shows another way to specify the reference, - // such that, the compiler will resolve the reference - // - - // the following cref shows how to hard-code the reference - /// - /// - class B { } - - /// - /// - /// - class C { } - - class Program - { - static void Main() { } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap12 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class TestClass - public class TestClass - { - /// DoWork is a method in the TestClass class. - /// Here's how you could make a second paragraph in a description. for information about output statements. - /// - /// - public static void DoWork(int Int1) - { - } - - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap13 -{ - // - // compile with: -doc:DocFileName.xml - - /// comment for class - public class TestClass - { - /// - /// Creates a new array of arbitrary type - /// - /// The element type of the array - public static T[] mkArray(int n) - { - return new T[n]; - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap14 -{ - // - // compile with: -doc:DocFileName.xml - - /// text for class Employee - public class Employee - { - private string _name; - - /// The Name property represents the employee's name. - /// The Name property gets/sets the value of the string field, _name. - - public string Name - { - get - { - return _name; - } - set - { - _name = value; - } - } - } - - /// text for class MainClass - public class MainClass - { - /// text for Main - static void Main() - { - } - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap15 -{ - // - // If compiling from the command line, compile with: -doc:YourFileName.xml - - /// - /// Class level summary documentation goes here. - /// - /// - /// Longer comments can be associated with a type or member through - /// the remarks tag. - /// - public class TestClass : TestInterface - { - /// - /// Store for the Name property. - /// - private string _name = null; - - /// - /// The class constructor. - /// - public TestClass() - { - // TODO: Add Constructor Logic here. - } - - /// - /// Name property. - /// - /// - /// A value tag is used to describe the property value. - /// - public string Name - { - get - { - if (_name == null) - { - throw new System.Exception("Name is null"); - } - return _name; - } - } - - /// - /// Description for SomeMethod. - /// - /// Parameter description for s goes here. - /// - /// You can use the cref attribute on any tag to reference a type or member - /// and the compiler will check that the reference exists. - /// - public void SomeMethod(string s) - { - } - - /// - /// Some other method. - /// - /// - /// Return values are described through the returns tag. - /// - /// - /// Notice the use of the cref attribute to reference a specific method. - /// - public int SomeOtherMethod() - { - return 0; - } - - public int InterfaceMethod(int n) - { - return n * n; - } - - /// - /// The entry point for the application. - /// - /// A list of command line arguments. - static int Main(System.String[] args) - { - // TODO: Add code to start application here. - return 0; - } - } - - /// - /// Documentation that describes the interface goes here. - /// - /// - /// Details about the interface go here. - /// - interface TestInterface - { - /// - /// Documentation that describes the method goes here. - /// - /// - /// Parameter n requires an integer argument. - /// - /// - /// The method returns an integer. - /// - int InterfaceMethod(int n); - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap16 -{ - // - // compile with: -doc:DocFileName.xml - - /// - /// You may have some primary information about this class. - /// - public class MainClass - { - } - - /// - public class TestClass: MainClass - { - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap17 -{ - // - // compile with: -doc:DocFileName.xml - - /// - /// You may have some primary information about this interface. - /// - public interface ITestInterface - { - } - - /// - public class TestClass : ITestInterface - { - } - // -} - -//----------------------------------------------------------------------------- -namespace Wrap18 -{ - // - // compile with: -doc:DocFileName.xml - - public class InheritOnlyReturns - { - /// In this example, this summary is only visible for this method. - /// A boolean - public static bool MyParentMethod(bool x) { return x; } - - /// - public static bool MyChildMethod() { return false; } - } - // -} - -namespace Wrap19 -{ - // - // compile with: -doc:DocFileName.xml - - public class InheritAllButRemarks - { - /// In this example, this summary is visible on all the methods. - /// The remarks. - /// A boolean - public static bool MyParentMethod(bool x) { return x; } - - /// - public static bool MyChildMethod() { return false; } - } - // -} diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuidePointers/CS/Pointers.cs b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuidePointers/CS/Pointers.cs index 044c86a79f179..050c3ac5ff0b1 100644 --- a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuidePointers/CS/Pointers.cs +++ b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuidePointers/CS/Pointers.cs @@ -8,16 +8,28 @@ static unsafe void Copy(byte[] source, int sourceOffset, byte[] target, int targetOffset, int count) { // If either array is not instantiated, you cannot complete the copy. - if ((source == null) || (target == null)) + if (source == null) { - throw new System.ArgumentException(); + throw new System.ArgumentException("neither array can be null.", nameof(source)); + } + if (target == null) + { + throw new System.ArgumentException("neither array can be null.", nameof(target)); } // If either offset, or the number of bytes to copy, is negative, you // cannot complete the copy. - if ((sourceOffset < 0) || (targetOffset < 0) || (count < 0)) + if (sourceOffset < 0) + { + throw new System.ArgumentException("offsets and count must be non-negative.", nameof(sourceOffset)); + } + if (targetOffset < 0) + { + throw new System.ArgumentException("offsets and count must be non-negative.", nameof(targetOffset)); + } + if (count < 0) { - throw new System.ArgumentException(); + throw new System.ArgumentException("offsets and count must be non-negative.", nameof(count)); } // If the number of bytes from the offset to the end of the array is @@ -26,7 +38,7 @@ static unsafe void Copy(byte[] source, int sourceOffset, byte[] target, if ((source.Length - sourceOffset < count) || (target.Length - targetOffset < count)) { - throw new System.ArgumentException(); + throw new System.InvalidOperationException("Cannot copy past the end of source or destination array."); } // The following fixed statement pins the location of the source and @@ -150,119 +162,6 @@ static void Main() } // -//----------------------------------------------------------------------------- -// -namespace N -{ - /// - /// Enter description here for class X. - /// ID string generated is "T:N.X". - /// - public unsafe class X - { - /// - /// Enter description here for the first constructor. - /// ID string generated is "M:N.X.#ctor". - /// - public X() { } - - /// - /// Enter description here for the second constructor. - /// ID string generated is "M:N.X.#ctor(System.Int32)". - /// - /// Describe parameter. - public X(int i) { } - - /// - /// Enter description here for field q. - /// ID string generated is "F:N.X.q". - /// - public string q; - - /// - /// Enter description for constant PI. - /// ID string generated is "F:N.X.PI". - /// - public const double PI = 3.14; - - /// - /// Enter description for method f. - /// ID string generated is "M:N.X.f". - /// - /// Describe return value. - public int f() { return 1; } - - /// - /// Enter description for method bb. - /// ID string generated is "M:N.X.bb(System.String,System.Int32@,System.Void*)". - /// - /// Describe parameter. - /// Describe parameter. - /// Describe parameter. - /// Describe return value. - public int bb(string s, ref int y, void* z) { return 1; } - - /// - /// Enter description for method gg. - /// ID string generated is "M:N.X.gg(System.Int16[],System.Int32[0:,0:])". - /// - /// Describe parameter. - /// Describe parameter. - /// Describe return value. - public int gg(short[] array1, int[,] array) { return 0; } - - /// - /// Enter description for operator. - /// ID string generated is "M:N.X.op_Addition(N.X,N.X)". - /// - /// Describe parameter. - /// Describe parameter. - /// Describe return value. - public static X operator +(X x, X xx) { return x; } - - /// - /// Enter description for property. - /// ID string generated is "P:N.X.prop". - /// - public int prop { get { return 1; } set { } } - - /// - /// Enter description for event. - /// ID string generated is "E:N.X.d". - /// - public event D d; - - /// - /// Enter description for property. - /// ID string generated is "P:N.X.Item(System.String)". - /// - /// Describe parameter. - /// - public int this[string s] { get { return 1; } } - - /// - /// Enter description for class Nested. - /// ID string generated is "T:N.X.Nested". - /// - public class Nested { } - - /// - /// Enter description for delegate. - /// ID string generated is "T:N.X.D". - /// - /// Describe parameter. - public delegate void D(int i); - - /// - /// Enter description for operator. - /// ID string generated is "M:N.X.op_Explicit(N.X)~System.Int32". - /// - /// Describe parameter. - /// Describe return value. - public static explicit operator int(X x) { return 1; } - } -} -// //----------------------------------------------------------------------------- // diff --git a/samples/snippets/csharp/concepts/codedoc/c-tag.cs b/samples/snippets/csharp/concepts/codedoc/c-tag.cs deleted file mode 100644 index 2434af1b8eed4..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/c-tag.cs +++ /dev/null @@ -1,11 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ -} \ No newline at end of file diff --git a/samples/snippets/csharp/concepts/codedoc/example-tag.cs b/samples/snippets/csharp/concepts/codedoc/example-tag.cs deleted file mode 100644 index c037a7b6d9979..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/example-tag.cs +++ /dev/null @@ -1,25 +0,0 @@ -// Adds two integers and returns the result -/// -/// Adds two integers and returns the result. -/// -/// -/// The sum of two integers. -/// -/// -/// -/// int c = Math.Add(4, 5); -/// if (c > 10) -/// { -/// Console.WriteLine(c); -/// } -/// -/// -public static int Add(int a, int b) -{ - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; -} diff --git a/samples/snippets/csharp/concepts/codedoc/exception-tag.cs b/samples/snippets/csharp/concepts/codedoc/exception-tag.cs deleted file mode 100644 index 780a19bbf1539..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/exception-tag.cs +++ /dev/null @@ -1,75 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Adds two integers and returns the result. - /// - /// - /// The sum of two integers. - /// - /// - /// - /// int c = Math.Add(4, 5); - /// if (c > 10) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when one parameter is max - /// and the other is greater than 0. - public static int Add(int a, int b) - { - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - /// - /// Adds two doubles and returns the result. - /// - /// - /// The sum of two doubles. - /// - /// Thrown when one parameter is max - /// and the other is greater than zero. - public static double Add(double a, double b) - { - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - /// - /// Divides an integer by another and returns the result. - /// - /// - /// The division of two integers. - /// - /// Thrown when a division by zero occurs. - public static int Divide(int a, int b) - { - return a / b; - } - - /// - /// Divides a double by another and returns the result. - /// - /// - /// The division of two doubles. - /// - /// Thrown when a division by zero occurs. - public static double Divide(double a, double b) - { - return a / b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/include-tag.cs b/samples/snippets/csharp/concepts/codedoc/include-tag.cs deleted file mode 100644 index 282bb0fcf1e9c..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/include-tag.cs +++ /dev/null @@ -1,73 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -public class Math -{ - // Adds two integers and returns the result - /// - public static int Add(int a, int b) - { - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - // Adds two doubles and returns the result - /// - public static double Add(double a, double b) - { - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - // Subtracts an integer from another and returns the result - /// - public static int Subtract(int a, int b) - { - return a - b; - } - - // Subtracts a double from another and returns the result - /// - public static double Subtract(double a, double b) - { - return a - b; - } - - // Multiplies two integers and returns the result - /// - public static int Multiply(int a, int b) - { - return a * b; - } - - // Multiplies two doubles and returns the result - /// - public static double Multiply(double a, double b) - { - return a * b; - } - - // Divides an integer by another and returns the result - /// - public static int Divide(int a, int b) - { - return a / b; - } - - // Divides a double by another and returns the result - /// - public static double Divide(double a, double b) - { - return a / b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/include.xml b/samples/snippets/csharp/concepts/codedoc/include.xml deleted file mode 100644 index d667c03273a3f..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/include.xml +++ /dev/null @@ -1,204 +0,0 @@ - - - - - The main Math class. - Contains all methods for performing basic math functions. - - - This class can add, subtract, multiply and divide. - These operations can be performed on both integers and doubles. - - - - - Adds two integers and and returns the result. - - - The sum of two integers. - - - - int c = Math.Add(4, 5); - if (c > 10) - { - Console.WriteLine(c); - } - - - Thrown when one parameter is max - and the other is greater than 0. - See to add doubles. - - - - An integer. - An integer. - - - - Adds two doubles and and returns the result. - - - The sum of two doubles. - - - - double c = Math.Add(4.5, 5.4); - if (c > 10) - { - Console.WriteLine(c); - } - - - Thrown when one parameter is max - and the other is greater than 0. - See to add integers. - - - - A double precision number. - A double precision number. - - - - Subtracts from and returns the result. - - - The difference between two integers. - - - - int c = Math.Subtract(4, 5); - if (c > 1) - { - Console.WriteLine(c); - } - - - See to subtract doubles. - - - - An integer. - An integer. - - - - Subtracts a double from another double and returns the result. - - - The difference between two doubles. - - - - double c = Math.Subtract(4.5, 5.4); - if (c > 1) - { - Console.WriteLine(c); - } - - - See to subtract integers. - - - - A double precision number. - A double precision number. - - - - Multiplies two integers and and returns the result. - - - The product of two integers. - - - - int c = Math.Multiply(4, 5); - if (c > 100) - { - Console.WriteLine(c); - } - - - See to multiply doubles. - - - - An integer. - An integer. - - - - Multiplies two doubles and and returns the result. - - - The product of two doubles. - - - - double c = Math.Multiply(4.5, 5.4); - if (c > 100.0) - { - Console.WriteLine(c); - } - - - See to multiply integers. - - - - A double precision number. - A double precision number. - - - - Divides an integer by another integer and returns the result. - - - The quotient of two integers. - - - - int c = Math.Divide(4, 5); - if (c > 1) - { - Console.WriteLine(c); - } - - - Thrown when is equal to 0. - See to divide doubles. - - - - An integer dividend. - An integer divisor. - - - - Divides a double by another double and returns the result. - - - The quotient of two doubles. - - - - double c = Math.Divide(4.5, 5.4); - if (c > 1.0) - { - Console.WriteLine(c); - } - - - Thrown when is equal to 0. - See to divide integers. - - - - A double precision dividend. - A double precision divisor. - - - diff --git a/samples/snippets/csharp/concepts/codedoc/inheritdoc-tag.cs b/samples/snippets/csharp/concepts/codedoc/inheritdoc-tag.cs deleted file mode 100644 index 4194a8da7098a..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/inheritdoc-tag.cs +++ /dev/null @@ -1,16 +0,0 @@ -/* - The IMath interface - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// This is the IMath interface. -/// -public interface IMath -{ -} - -/// -public class Math : IMath -{ -} \ No newline at end of file diff --git a/samples/snippets/csharp/concepts/codedoc/list-tag.cs b/samples/snippets/csharp/concepts/codedoc/list-tag.cs deleted file mode 100644 index acae0676094fa..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/list-tag.cs +++ /dev/null @@ -1,29 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -/// -/// Add -/// Addition Operation -/// -/// -/// Subtract -/// Subtraction Operation -/// -/// -/// Multiply -/// Multiplication Operation -/// -/// -/// Divide -/// Division Operation -/// -/// -/// -public class Math -{ -} diff --git a/samples/snippets/csharp/concepts/codedoc/para-tag.cs b/samples/snippets/csharp/concepts/codedoc/para-tag.cs deleted file mode 100644 index e1b447e9dedd9..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/para-tag.cs +++ /dev/null @@ -1,15 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -/// -/// This class can add, subtract, multiply and divide. -/// These operations can be performed on both integers and doubles. -/// -public class Math -{ -} diff --git a/samples/snippets/csharp/concepts/codedoc/param-tag.cs b/samples/snippets/csharp/concepts/codedoc/param-tag.cs deleted file mode 100644 index 9314029c403c9..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/param-tag.cs +++ /dev/null @@ -1,29 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Adds two doubles and returns the result. - /// - /// - /// The sum of two doubles. - /// - /// Thrown when one parameter is max - /// and the other is greater than zero. - /// See to add integers. - /// A double precision number. - /// A double precision number. - public static double Add(double a, double b) - { - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/paramref-tag.cs b/samples/snippets/csharp/concepts/codedoc/paramref-tag.cs deleted file mode 100644 index ffbe79e86dfc9..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/paramref-tag.cs +++ /dev/null @@ -1,29 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Adds two doubles and and returns the result. - /// - /// - /// The sum of two doubles. - /// - /// Thrown when one parameter is max - /// and the other is greater than zero. - /// See to add integers. - /// A double precision number. - /// A double precision number. - public static double Add(double a, double b) - { - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/remarks-tag.cs b/samples/snippets/csharp/concepts/codedoc/remarks-tag.cs deleted file mode 100644 index dfa70f721acbd..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/remarks-tag.cs +++ /dev/null @@ -1,14 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -/// -/// This class can add, subtract, multiply and divide. -/// -public class Math -{ -} diff --git a/samples/snippets/csharp/concepts/codedoc/returns-tag.cs b/samples/snippets/csharp/concepts/codedoc/returns-tag.cs deleted file mode 100644 index 5ec9fdb756dd3..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/returns-tag.cs +++ /dev/null @@ -1,16 +0,0 @@ -// Adds two integers and returns the result -/// -/// Adds two integers and returns the result. -/// -/// -/// The sum of two integers. -/// -public static int Add(int a, int b) -{ - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; -} diff --git a/samples/snippets/csharp/concepts/codedoc/sample-library.cs b/samples/snippets/csharp/concepts/codedoc/sample-library.cs deleted file mode 100644 index 56dc94cf9d972..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/sample-library.cs +++ /dev/null @@ -1,62 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -public class Math -{ - // Adds two integers and returns the result - public static int Add(int a, int b) - { - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - // Adds two doubles and returns the result - public static double Add(double a, double b) - { - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - // Subtracts an integer from another and returns the result - public static int Subtract(int a, int b) - { - return a - b; - } - - // Subtracts a double from another and returns the result - public static double Subtract(double a, double b) - { - return a - b; - } - - // Multiplies two integers and returns the result - public static int Multiply(int a, int b) - { - return a * b; - } - - // Multiplies two doubles and returns the result - public static double Multiply(double a, double b) - { - return a * b; - } - - // Divides an integer by another and returns the result - public static int Divide(int a, int b) - { - return a / b; - } - - // Divides a double by another and returns the result - public static double Divide(double a, double b) - { - return a / b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/see-tag.cs b/samples/snippets/csharp/concepts/codedoc/see-tag.cs deleted file mode 100644 index a29dfcf27369a..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/see-tag.cs +++ /dev/null @@ -1,53 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Adds two integers and returns the result. - /// - /// - /// The sum of two integers. - /// - /// - /// - /// int c = Math.Add(4, 5); - /// if (c > 10) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when one parameter is max - /// and the other is greater than 0. - /// See to add doubles. - public static int Add(int a, int b) - { - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - /// - /// Adds two doubles and returns the result. - /// - /// - /// The sum of two doubles. - /// - /// Thrown when one parameter is max - /// and the other is greater than zero. - /// See to add integers. - public static double Add(double a, double b) - { - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/seealso-tag.cs b/samples/snippets/csharp/concepts/codedoc/seealso-tag.cs deleted file mode 100644 index 6f40105455e75..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/seealso-tag.cs +++ /dev/null @@ -1,39 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Adds two integers and returns the result. - /// - /// - /// The sum of two integers. - /// - /// - /// - /// int c = Math.Add(4, 5); - /// if (c > 10) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when one parameter is max - /// and the other is greater than 0. - /// See to add doubles. - /// - /// - /// - public static int Add(int a, int b) - { - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/summary-tag.cs b/samples/snippets/csharp/concepts/codedoc/summary-tag.cs deleted file mode 100644 index 10e28c6bf8d78..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/summary-tag.cs +++ /dev/null @@ -1,24 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - // Adds two integers and returns the result - /// - /// Adds two integers and returns the result. - /// - public static int Add(int a, int b) - { - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/tagged-library.cs b/samples/snippets/csharp/concepts/codedoc/tagged-library.cs deleted file mode 100644 index ead203e889296..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/tagged-library.cs +++ /dev/null @@ -1,264 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -/// -/// Add -/// Addition Operation -/// -/// -/// Subtract -/// Subtraction Operation -/// -/// -/// Multiply -/// Multiplication Operation -/// -/// -/// Divide -/// Division Operation -/// -/// -/// -/// -/// This class can add, subtract, multiply and divide. -/// These operations can be performed on both integers and doubles. -/// -public class Math -{ - // Adds two integers and returns the result - /// - /// Adds two integers and and returns the result. - /// - /// - /// The sum of two integers. - /// - /// - /// - /// int c = Math.Add(4, 5); - /// if (c > 10) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when one parameter is max - /// and the other is greater than 0. - /// See to add doubles. - /// - /// - /// - /// An integer. - /// An integer. - public static int Add(int a, int b) - { - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - // Adds two doubles and returns the result - /// - /// Adds two doubles and and returns the result. - /// - /// - /// The sum of two doubles. - /// - /// - /// - /// double c = Math.Add(4.5, 5.4); - /// if (c > 10) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when one parameter is max - /// and the other is greater than 0. - /// See to add integers. - /// - /// - /// - /// A double precision number. - /// A double precision number. - public static double Add(double a, double b) - { - // If any parameter is equal to the max value of an integer - // and the other is greater than zero - if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) - throw new System.OverflowException(); - - return a + b; - } - - // Subtracts an integer from another and returns the result - /// - /// Subtracts from and returns the result. - /// - /// - /// The difference between two integers. - /// - /// - /// - /// int c = Math.Subtract(4, 5); - /// if (c > 1) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// See to subtract doubles. - /// - /// - /// - /// An integer. - /// An integer. - public static int Subtract(int a, int b) - { - return a - b; - } - - // Subtracts a double from another and returns the result - /// - /// Subtracts a double from another double and returns the result. - /// - /// - /// The difference between two doubles. - /// - /// - /// - /// double c = Math.Subtract(4.5, 5.4); - /// if (c > 1) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// See to subtract integers. - /// - /// - /// - /// A double precision number. - /// A double precision number. - public static double Subtract(double a, double b) - { - return a - b; - } - - // Multiplies two integers and returns the result - /// - /// Multiplies two integers and and returns the result. - /// - /// - /// The product of two integers. - /// - /// - /// - /// int c = Math.Multiply(4, 5); - /// if (c > 100) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// See to multiply doubles. - /// - /// - /// - /// An integer. - /// An integer. - public static int Multiply(int a, int b) - { - return a * b; - } - - // Multiplies two doubles and returns the result - /// - /// Multiplies two doubles and and returns the result. - /// - /// - /// The product of two doubles. - /// - /// - /// - /// double c = Math.Multiply(4.5, 5.4); - /// if (c > 100.0) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// See to multiply integers. - /// - /// - /// - /// A double precision number. - /// A double precision number. - public static double Multiply(double a, double b) - { - return a * b; - } - - // Divides an integer by another and returns the result - /// - /// Divides an integer by another integer and returns the result. - /// - /// - /// The quotient of two integers. - /// - /// - /// - /// int c = Math.Divide(4, 5); - /// if (c > 1) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when is equal to 0. - /// See to divide doubles. - /// - /// - /// - /// An integer dividend. - /// An integer divisor. - public static int Divide(int a, int b) - { - return a / b; - } - - // Divides a double by another and returns the result - /// - /// Divides a double by another double and returns the result. - /// - /// - /// The quotient of two doubles. - /// - /// - /// - /// double c = Math.Divide(4.5, 5.4); - /// if (c > 1.0) - /// { - /// Console.WriteLine(c); - /// } - /// - /// - /// Thrown when is equal to 0. - /// See to divide integers. - /// - /// - /// - /// A double precision dividend. - /// A double precision divisor. - public static double Divide(double a, double b) - { - return a / b; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/typeparam-tag.cs b/samples/snippets/csharp/concepts/codedoc/typeparam-tag.cs deleted file mode 100644 index a57e499b88a30..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/typeparam-tag.cs +++ /dev/null @@ -1,19 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Checks if an IComparable is greater than another. - /// - /// A type that inherits from the IComparable interface. - public static bool GreaterThan(T a, T b) where T : IComparable - { - return a.CompareTo(b) > 0; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/typeparamref-tag.cs b/samples/snippets/csharp/concepts/codedoc/typeparamref-tag.cs deleted file mode 100644 index 3df824f6d1968..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/typeparamref-tag.cs +++ /dev/null @@ -1,19 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -public class Math -{ - /// - /// Checks if an IComparable is greater than another. - /// - /// A type that inherits from the IComparable interface. - public static bool GreaterThan(T a, T b) where T : IComparable - { - return a.CompareTo(b) > 0; - } -} diff --git a/samples/snippets/csharp/concepts/codedoc/value-tag.cs b/samples/snippets/csharp/concepts/codedoc/value-tag.cs deleted file mode 100644 index 8b8b54e974d01..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/value-tag.cs +++ /dev/null @@ -1,17 +0,0 @@ -/* - The main Math class - Contains all methods for performing basic math functions -*/ -/// -/// The main Math class. -/// Contains all methods for performing basic math functions. -/// -/// -/// This class can add, subtract, multiply and divide. -/// These operations can be performed on both integers and doubles -/// -public class Math -{ - /// Gets the value of PI. - public static double PI { get; } -} diff --git a/samples/snippets/csharp/concepts/codedoc/xml-comment.cs b/samples/snippets/csharp/concepts/codedoc/xml-comment.cs deleted file mode 100644 index c8f103e711526..0000000000000 --- a/samples/snippets/csharp/concepts/codedoc/xml-comment.cs +++ /dev/null @@ -1,6 +0,0 @@ -/// -/// This class does something. -/// -public class SomeClass -{ -}