|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
using System.Globalization;
using System.Threading;
namespace Microsoft.CodeAnalysis
{
/// <summary>
/// A class used to provide XML documentation to the compiler for members from metadata. A
/// custom implementation of this class should be returned from a DocumentationResolver to provide XML
/// documentation comments from custom caches or locations.
/// </summary>
public abstract partial class DocumentationProvider
{
public static DocumentationProvider Default { get; } = new NullDocumentationProvider();
protected DocumentationProvider()
{
}
/// <summary>
/// Fetches a documentation comment for the given member ID.
/// </summary>
/// <param name="documentationMemberID">The documentation member ID of the item to fetch.</param>
/// <param name="preferredCulture">The preferred culture to receive a comment in. Null if
/// there is no preference. This is a preference only, and providers may choose to provide
/// results from another culture if the preferred culture was unavailable.</param>
/// <param name="cancellationToken">A cancellation token for the search.</param>
/// <returns>A DocumentationComment.</returns>
protected internal abstract string? GetDocumentationForSymbol(
string documentationMemberID,
CultureInfo preferredCulture,
CancellationToken cancellationToken = default);
/// <summary>
/// DocumentationProviders are compared when determining whether an AssemblySymbol can be reused.
/// Hence, if multiple instances can represent the same documentation, it is imperative that
/// Equals (and GetHashCode) be overridden to capture this fact. Otherwise, it is possible to end
/// up with multiple AssemblySymbols for the same assembly, which plays havoc with the type hierarchy.
/// </summary>
public abstract override bool Equals(object? obj);
/// <summary>
/// DocumentationProviders are compared when determining whether an AssemblySymbol can be reused.
/// Hence, if multiple instances can represent the same documentation, it is imperative that
/// GetHashCode (and Equals) be overridden to capture this fact. Otherwise, it is possible to end
/// up with multiple AssemblySymbols for the same assembly, which plays havoc with the type hierarchy.
/// </summary>
public abstract override int GetHashCode();
}
}
|