diff --git a/docs/docs/basic-concepts.md b/docs/docs/basic-concepts.md index 7d9680fa63a..8a90eb3fb3d 100644 --- a/docs/docs/basic-concepts.md +++ b/docs/docs/basic-concepts.md @@ -15,10 +15,28 @@ Docfx can be used as a static site generator, but the real value of the tool is /// Individual's date of birth. /// Date at which to evaluate age at. /// Age of the individual in years (as an integer). - /// This code is not guaranteed to be correct for non-UK locales, as some countries have skipped certain dates - /// within living memory. + /// Thrown when is earlier than . + /// + /// This example shows how to use the extension method: + /// + /// DateOnly birthDate = new DateOnly(1990, 5, 25); + /// DateOnly today = DateOnly.FromDateTime(DateTime.Today); + /// int age = birthDate.AgeAt(today); + /// Console.WriteLine($"The person is {age} years old."); + /// + /// + /// + /// This code is not guaranteed to be correct for non-UK locales, as some countries have skipped certain dates + /// within living memory. + /// See Leap Year for more information on leap year calculations. + /// + /// + /// DateOnly Class public static int AgeAt(this DateOnly dateOfBirth, DateOnly date) { + if (date < dateOfBirth) + throw new ArgumentOutOfRangeException(nameof(date), "Date cannot be earlier than date of birth"); + int age = date.Year - dateOfBirth.Year; return dateOfBirth > date.AddYears(-age) ? --age : age; @@ -33,6 +51,8 @@ Static documentation pages are prepared using [Markdown](markdown.md) (slightly Once the API documentation has been parsed from the source code, it is compiled along with the Markdown content into a set of HTML pages which can be published on a website. It is also possible to compile the final output into one or more PDFs for offline use. +DocFX supports a wide range of XML comment tags. The example above demonstrates some of the commonly used tags, but for a comprehensive guide to all supported XML comment tags and how they appear in the generated documentation, see the [XML Comment Examples](xml-comment-examples.md) page. + Docfx is a command-line tool that can be invoked directly, or as a .NET Core CLI tool using the `dotnet` command, but it can also be invoked from source code using the `Docset.Build` method in the `Docfx` namespace. It is configured using a JSON configuration file, [`docfx.json`](../reference/docfx-json-reference.md) which has sections for different parts of the build process. ## Consuming .NET projects diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml index 7f1b3a150c9..3393aded05e 100644 --- a/docs/docs/toc.yml +++ b/docs/docs/toc.yml @@ -1,5 +1,6 @@ - name: Get started - href: basic-concepts.md +- href: xml-comment-examples.md - href: ../index.md - name: Essentials diff --git a/docs/docs/xml-comment-examples.md b/docs/docs/xml-comment-examples.md new file mode 100644 index 00000000000..5f3dfe4d263 --- /dev/null +++ b/docs/docs/xml-comment-examples.md @@ -0,0 +1,493 @@ +# XML Comment Examples + +## Introduction + +This page provides comprehensive examples of XML comments that DocFX supports for generating API documentation. The examples cover all major XML comment tags and demonstrate how they are rendered in the generated documentation. + +## Basic XML Comment Tags + +### Summary + +The `` tag provides a brief description of the type or member. + +```csharp +/// +/// Represents a collection of key/value pairs that are organized +/// based on the hash code of the key. +/// +public class Dictionary : IDictionary +{ + // Implementation +} +``` + +### Parameters + +The `` tag describes a parameter for a method or constructor. + +```csharp +/// +/// Adds an element with the specified key and value. +/// +/// The key of the element to add. +/// The value of the element to add. +/// is null. +/// An element with the same key already exists. +public void Add(TKey key, TValue value) +{ + // Implementation +} +``` + +### Type Parameters + +The `` tag describes a generic type parameter. + +```csharp +/// +/// Represents a strongly typed list of objects that can be accessed by index. +/// +/// The type of elements in the list. +public class List : IList +{ + // Implementation +} +``` + +### Returns + +The `` tag describes the return value of a method. + +```csharp +/// +/// Gets the value associated with the specified key. +/// +/// The key of the value to get. +/// The value associated with the specified key. If the key is not found, +/// the method throws a . +/// is null. +/// The key does not exist in the collection. +public TValue GetValue(TKey key) +{ + // Implementation +} +``` + +### Value + +The `` tag describes the value that a property represents. + +```csharp +/// +/// Gets the number of key/value pairs contained in the dictionary. +/// +/// The number of key/value pairs contained in the dictionary. +public int Count +{ + get { /* Implementation */ } +} +``` + +## Advanced XML Comment Tags + +### Remarks + +The `` tag provides additional information about a type or member, supplementing the information in the `` tag. + +```csharp +/// +/// Represents a unique identifier. +/// +/// +/// The Guid structure provides a unique identification number. +/// The following example demonstrates how to create a new Guid: +/// +/// Guid g = Guid.NewGuid(); +/// +/// +public struct Guid : IComparable, IFormattable +{ + // Implementation +} +``` + +### Example + +The `` tag provides example code for how to use a method or other library member. + +```csharp +/// +/// Converts the string representation of a number to its 32-bit signed integer equivalent. +/// +/// A string containing a number to convert. +/// A 32-bit signed integer equivalent to the number contained in . +/// +/// The following example demonstrates how to convert a string to an integer: +/// +/// string numberString = "123"; +/// int number = Int32.Parse(numberString); +/// Console.WriteLine(number); // Output: 123 +/// +/// +public static int Parse(string s) +{ + // Implementation +} +``` + +### Exception + +The `` tag documents the exceptions a method can throw. + +```csharp +/// +/// Creates a shallow copy of the current object. +/// +/// A shallow copy of the current object. +/// The current type does not implement the interface. +/// The caller does not have access to the method implementation. +public object Clone() +{ + // Implementation +} +``` + +### See Also + +The `` tag creates a cross-reference to another type or member. + +```csharp +/// +/// Represents an instant in time, typically expressed as a date and time of day. +/// +/// +/// For more information about working with dates and times, see the structure. +/// +/// +/// +/// Date and time in .NET +public struct DateTime : IComparable, IFormattable +{ + // Implementation +} +``` + +### See + +The `` tag provides an inline cross-reference to another type or member. + +```csharp +/// +/// Compares this instance to a specified object and returns an integer that +/// indicates whether this instance is earlier than, the same as, or later than the +/// specified object. +/// +/// An object to compare with this instance. +/// +/// A signed number indicating the relative values of this instance and the value parameter. +/// Less than zero if this instance is earlier than object. +/// Zero if this instance is the same as object. +/// Greater than zero if this instance is later than object. +/// +/// +/// See the interface for more information. +/// +public int CompareTo(object obj) +{ + // Implementation +} +``` + +## Formatting and Special Tags + +### Inline Code + +The `` tag formats text as code in an inline context. + +```csharp +/// +/// The StringBuilder class represents a mutable string of characters. +/// +public sealed class StringBuilder : ISerializable +{ + // Implementation +} +``` + +### Code Block + +The `` tag formats a block of text as code. + +```csharp +/// +/// Represents a JSON array. +/// +/// +/// You can create a JSON array using the following code: +/// +/// var jsonArray = new JsonArray(); +/// jsonArray.Add(1); +/// jsonArray.Add("text"); +/// jsonArray.Add(true); +/// +/// +public class JsonArray : JsonElement +{ + // Implementation +} +``` + +### Lists + +The `` tag creates a list or table. + +```csharp +/// +/// Defines special behaviors for serialization. +/// +/// +/// +/// Use to enable serialization of a type. +/// Use to disable serialization of a specific member. +/// Use for more precise control over serialization. +/// +/// +public class SerializationBehavior +{ + // Implementation +} +``` + +```csharp +/// +/// Provides a description of the HTTP status codes. +/// +/// +/// +/// +/// Status Code +/// Description +/// +/// +/// 200 +/// OK. The request has succeeded. +/// +/// +/// 404 +/// Not Found. The requested resource does not exist. +/// +/// +/// 500 +/// Internal Server Error. An unexpected server error occurred. +/// +/// +/// +public enum HttpStatusCode +{ + // Implementation +} +``` + +### Notes + +The `` tag creates a note with various types. + +```csharp +/// +/// Encrypts data using the specified algorithm. +/// +/// The data to encrypt. +/// The encryption key. +/// The encrypted data. +/// +/// +/// Always use a strong key and store it securely. +/// +/// +/// This method is not recommended for sensitive data. +/// +/// +/// The key must be the correct length for the algorithm chosen. +/// +/// +public byte[] Encrypt(byte[] data, byte[] key) +{ + // Implementation +} +``` + +### Paramrefs and Typeparamrefs + +The `` and `` tags identify words as parameters or type parameters, respectively. + +```csharp +/// +/// Gets the value associated with the specified key. +/// +/// The key whose value to get. +/// The type of the keys in the dictionary. +/// The type of the values in the dictionary. +/// +/// The value associated with the specified key. If is not found, +/// the method returns the default value for . +/// +public TValue GetValueOrDefault(TKey key) +{ + // Implementation +} +``` + +## Bringing It All Together + +Here's a comprehensive example that uses many of the XML comment tags together: + +```csharp +/// +/// Represents a generic cache that stores items with expiration policies. +/// +/// The type of keys used to identify cached items. +/// The type of items stored in the cache. +/// +/// The class provides a thread-safe way to store and retrieve items with expiration policies. +/// Items can be set to expire after a fixed duration, at a specific time, or based on a custom policy. +/// +/// This implementation is not distributed and is intended for use in a single-process application. +/// +/// +/// The cache supports the following expiration policies: +/// +/// +/// AbsoluteExpiration: Items expire at a specific point in time. +/// +/// +/// SlidingExpiration: Items expire after a period of inactivity. +/// +/// +/// CustomExpiration: Items expire based on a custom callback function. +/// +/// +/// +/// +/// Here's an example of how to use the Cache class: +/// +/// // Create a new cache +/// var cache = new Cache<string, User>(); +/// +/// // Add an item that expires after 10 minutes +/// cache.Set("user:123", new User { Id = 123, Name = "John" }, TimeSpan.FromMinutes(10)); +/// +/// // Retrieve the item +/// if (cache.TryGet("user:123", out User user)) +/// { +/// Console.WriteLine($"User name: {user.Name}"); +/// } +/// +/// +/// +/// Caching in .NET +public class Cache : IDisposable +{ + /// + /// Initializes a new instance of the class with default settings. + /// + /// + /// + /// var cache = new Cache<string, int>(); + /// + /// + public Cache() + { + // Implementation + } + + /// + /// Gets the number of items currently in the cache. + /// + /// The number of items in the cache. + /// + /// This count includes items that may have expired but haven't been removed yet. + /// Use to remove expired items. + /// + public int Count + { + get { /* Implementation */ } + } + + /// + /// Adds or updates an item in the cache with an absolute expiration time. + /// + /// The key of the item to add. + /// The value to add to the cache. + /// The absolute expiration date for the item. + /// true if the item was added; false if it was updated. + /// is null. + /// is in the past. + /// + /// + /// cache.Set("key", "value", DateTime.UtcNow.AddMinutes(30)); + /// + /// + public bool Set(TKey key, TValue value, DateTime absoluteExpiration) + { + // Implementation + return true; + } + + /// + /// Attempts to get a cached item by its key. + /// + /// The key of the item to get. + /// + /// When this method returns, contains the value associated with the specified key, + /// if the key is found; otherwise, the default value for the type of the value parameter. + /// + /// + /// true if the cache contains an item with the specified key and it has not expired; + /// otherwise, false. + /// + /// is null. + public bool TryGet(TKey key, out TValue value) + { + // Implementation + value = default; + return false; + } + + /// + /// Removes all expired items from the cache. + /// + /// The number of items that were removed. + /// + /// + /// This method is automatically called periodically by the cache maintenance task. + /// + /// + /// You can call this method manually if you want to immediately reclaim memory + /// used by expired items. + /// + /// + public int CleanExpiredItems() + { + // Implementation + return 0; + } + + /// + /// Releases all resources used by the cache. + /// + /// + /// Call this method when you're finished using the cache. + /// + public void Dispose() + { + // Implementation + } +} +``` + +## What's Next? + +For more information about XML documentation comments in C#, see: + +- [XML Documentation Comments (C# Programming Guide)](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) +- [Recommended XML tags for C# documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) \ No newline at end of file