// private protected constructor => prevent implementation outside of this assembly
private protected OverloadDocumentation(MemberId memberId, IXmlDocsProvider xmlDocsProvider)
{
MemberId = memberId ?? throw new ArgumentNullException(nameof(memberId));
var documentationComments = xmlDocsProvider.TryGetDocumentationComments(memberId);
Summary = documentationComments?.Summary ?? TextBlock.Empty;
Remarks = documentationComments?.Remarks ?? TextBlock.Empty;
SeeAlso = documentationComments?.SeeAlso?.AsReadOnlyList() ?? Array.Empty <SeeAlsoElement>();
Returns = documentationComments?.Returns ?? TextBlock.Empty;
Exceptions = documentationComments?.Exceptions?.AsReadOnlyList() ?? Array.Empty <ExceptionElement>();
Example = documentationComments?.Example ?? TextBlock.Empty;
}
/// <summary>
/// Initializes a new instance of <see cref="MethodLikeOverloadDocumentation"/>.
/// </summary>
/// <param name="definition">The underlying Mono.Cecil definition of the method overload.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
// private protected constructor => prevent implementation outside of this assembly
private protected MethodLikeOverloadDocumentation(MethodDefinition definition, IXmlDocsProvider xmlDocsProvider)
: base(definition.ToMemberId(), xmlDocsProvider)
{
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
m_XmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
Parameters = definition.HasParameters
? definition.Parameters.Select(p => new ParameterDocumentation(this, p, xmlDocsProvider)).ToArray()
: Array.Empty <ParameterDocumentation>();
Type = definition.ReturnType.ToTypeId();
TypeParameters = LoadTypeParameters();
Signature = SignatureFormatter.GetSignature(Definition);
CSharpDefinition = CSharpDefinitionFormatter.GetDefinition(definition);
IsObsolete = Definition.IsObsolete(out var obsoleteMessage);
ObsoleteMessage = obsoleteMessage;
}
/// <summary>
/// Initializes a new instance of <see cref="AssemblySetDocumentation"/>
/// </summary>
private AssemblySetDocumentation(IReadOnlyList <AssemblyDefinition> assemblyDefinitions, IXmlDocsProvider xmlDocsProvider, ILogger logger)
{
if (assemblyDefinitions is null)
{
throw new ArgumentNullException(nameof(assemblyDefinitions));
}
m_XmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
m_Logger = logger ?? throw new ArgumentNullException(nameof(logger));
m_Assemblies = new Dictionary <string, AssemblyDocumentation>(StringComparer.OrdinalIgnoreCase);
m_Namespaces = new Dictionary <NamespaceId, NamespaceDocumentation>();
m_Types = new Dictionary <TypeId, TypeDocumentation>();
Assemblies = ReadOnlyCollectionAdapter.Create(m_Assemblies.Values);
Namespaces = ReadOnlyCollectionAdapter.Create(m_Namespaces.Values);
Types = ReadOnlyCollectionAdapter.Create(m_Types.Values);
LoadAssemblies(assemblyDefinitions);
}
/// <summary>
/// Initializes a new instance of <see cref="IndexerOverloadDocumentation"/>
/// </summary>
/// <param name="indexerDocumentation">The documentation model of the indexer being overloaded.</param>
/// <param name="definition">The underlying Mono.Cecil definition of the indexer.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal IndexerOverloadDocumentation(
IndexerDocumentation indexerDocumentation,
PropertyDefinition definition,
IXmlDocsProvider xmlDocsProvider) : base(definition.ToMemberId(), xmlDocsProvider)
{
IndexerDocumentation = indexerDocumentation ?? throw new ArgumentNullException(nameof(indexerDocumentation));
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
xmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
Parameters = definition.HasParameters
? definition.Parameters.Select(p => new ParameterDocumentation(this, p, xmlDocsProvider)).ToArray()
: Array.Empty <ParameterDocumentation>();
Type = definition.PropertyType.ToTypeId();
Signature = SignatureFormatter.GetSignature(definition);
CSharpDefinition = CSharpDefinitionFormatter.GetDefinition(definition);
Value = xmlDocsProvider.TryGetDocumentationComments(MemberId)?.Value;
IsObsolete = definition.IsObsolete(out var obsoleteMessage);
ObsoleteMessage = obsoleteMessage;
}
// private protected constructor => prevent implementation outside of this assembly
private protected SimpleMemberDocumentation(TypeDocumentation typeDocumentation,
MemberId memberId,
IXmlDocsProvider xmlDocsProvider,
ICustomAttributeProvider definitionAttributes) : base(typeDocumentation)
{
if (xmlDocsProvider == null)
{
throw new ArgumentNullException(nameof(xmlDocsProvider));
}
MemberId = memberId ?? throw new ArgumentNullException(nameof(memberId));
definitionAttributes = definitionAttributes ?? throw new ArgumentNullException(nameof(definitionAttributes));
var documentationComments = xmlDocsProvider.TryGetDocumentationComments(memberId);
Summary = documentationComments?.Summary ?? TextBlock.Empty;
Remarks = documentationComments?.Remarks ?? TextBlock.Empty;
SeeAlso = documentationComments?.SeeAlso?.AsReadOnlyList() ?? Array.Empty <SeeAlsoElement>();
Example = documentationComments?.Example ?? TextBlock.Empty;
IsObsolete = definitionAttributes.IsObsolete(out var obsoleteMessage);
ObsoleteMessage = obsoleteMessage;
}
/// <summary>
/// Initializes a new instance of <see cref="TypeParameterDocumentation"/>.
/// </summary>
/// <param name="parent">The parent documentation model (the type of method that defines the type parameter).</param>
/// <param name="parentId">The if of the parent documentation model (the type of method that defines the type parameter).</param>
/// <param name="definition">The underlying Mono.Cecil definition of the type parameter.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal TypeParameterDocumentation(IAssemblyMemberDocumentation parent, MemberId parentId, GenericParameter definition, IXmlDocsProvider xmlDocsProvider)
{
m_Parent = parent;
parentId = parentId ?? throw new ArgumentNullException(nameof(parentId));
Definition = definition;
xmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
Description = xmlDocsProvider.TryGetDocumentationComments(parentId)?.TypeParameters?.GetValueOrDefault(definition.Name);
}
/// <summary>
/// Initializes a new instance of <see cref="MethodOverloadDocumentation"/>.
/// </summary>
/// <param name="methodDocumentation">The documentation model of the method being overloaded.</param>
/// <param name="definition">The underlying Mono.Cecil definition of the method.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal MethodOverloadDocumentation(MethodDocumentation methodDocumentation, MethodDefinition definition, IXmlDocsProvider xmlDocsProvider)
: base(definition, xmlDocsProvider)
{
MethodDocumentation = methodDocumentation ?? throw new ArgumentNullException(nameof(methodDocumentation));
}
/// <summary>
/// Initializes a new instance of <see cref="MethodDocumentation"/>.
/// </summary>
/// <param name="typeDocumentation">The documentation model of the type defining the method.</param>
/// <param name="definitions">The Mono.Cecil definitions for all the method's overloads.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal MethodDocumentation(TypeDocumentation typeDocumentation, IEnumerable <MethodDefinition> definitions, IXmlDocsProvider xmlDocsProvider) : base(typeDocumentation)
{
if (definitions == null)
{
throw new ArgumentNullException(nameof(definitions));
}
if (definitions.Select(x => x.Name).Distinct().Count() > 1)
{
throw new ArgumentException("All definitions have to be overloads of the same method", nameof(definitions));
}
m_Overloads = definitions
.Select(d => new MethodOverloadDocumentation(this, d, xmlDocsProvider))
.ToDictionary(d => d.MemberId);
Overloads = ReadOnlyCollectionAdapter.Create(m_Overloads.Values);
Name = definitions.First().Name;
}
/// <summary>
/// Initializes a new instance of <see cref="FieldDocumentation"/>.
/// </summary>
/// <param name="typeDocumentation">The documentation model of the type defining the field.</param>
/// <param name="definition">The underlying Mono.Cecil definition of the field.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
/// <exception cref="ArgumentNullException">Thrown when one of the constructor arguments is null.</exception>
internal FieldDocumentation(TypeDocumentation typeDocumentation, FieldDefinition definition, IXmlDocsProvider xmlDocsProvider)
: base(typeDocumentation, definition.ToMemberId(), xmlDocsProvider, definition)
{
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
xmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
Type = definition.FieldType.ToTypeId();
CSharpDefinition = CSharpDefinitionFormatter.GetDefinition(definition);
Value = xmlDocsProvider.TryGetDocumentationComments(MemberId)?.Value ?? TextBlock.Empty;
}
internal OperatorOverloadDocumentation(OperatorDocumentation operatorDocumentation, MethodDefinition definition, IXmlDocsProvider xmlDocsProvider) : base(definition, xmlDocsProvider)
{
OperatorKind = definition.GetOperatorKind() ?? throw new ArgumentException($"Method {definition.Name} is not an operator overload");
OperatorDocumentation = operatorDocumentation ?? throw new ArgumentNullException(nameof(operatorDocumentation));
}
/// <summary>
/// Initializes a new instance of <see cref="PropertyDocumentation"/>.
/// </summary>
/// <param name="typeDocumentation">The documentation model of the type defining the property.</param>
/// <param name="definition">The underlying Mono.Cecil definition of the property.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal PropertyDocumentation(TypeDocumentation typeDocumentation, PropertyDefinition definition, IXmlDocsProvider xmlDocsProvider)
: base(typeDocumentation, definition.ToMemberId(), xmlDocsProvider, definition)
{
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
xmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
Type = definition.PropertyType.ToTypeId();
CSharpDefinition = CSharpDefinitionFormatter.GetDefinition(definition);
var documentationComments = xmlDocsProvider?.TryGetDocumentationComments(MemberId);
Value = documentationComments?.Value;
Exceptions = documentationComments?.Exceptions?.AsReadOnlyList() ?? Array.Empty <ExceptionElement>();
}
/// <summary>
/// Initializes a new instance of <see cref="EventDocumentation"/>.
/// </summary>
/// <param name="typeDocumentation">The documentation model of the type defining the event.</param>
/// <param name="definition">The underlying Mono.Cecil definition of the event.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
/// <exception cref="ArgumentNullException">Thrown when one of the constructor arguments is null.</exception>
internal EventDocumentation(TypeDocumentation typeDocumentation, EventDefinition definition, IXmlDocsProvider xmlDocsProvider)
: base(typeDocumentation, definition.ToMemberId(), xmlDocsProvider, definition)
{
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
Type = definition.EventType.ToTypeId();
CSharpDefinition = CSharpDefinitionFormatter.GetDefinition(definition);
}
/// <summary>
/// Initializes a new instance of <see cref="OperatorDocumentation"/>.
/// </summary>
/// <param name="typeDocumentation">The documentation model of the type defining the operator overload.</param>
/// <param name="definitions">The underlying Mono.Cecul definitions of the operator overload.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal OperatorDocumentation(TypeDocumentation typeDocumentation, IEnumerable <MethodDefinition> definitions, IXmlDocsProvider xmlDocsProvider)
: base(typeDocumentation)
{
if (definitions == null)
{
throw new ArgumentNullException(nameof(definitions));
}
if (definitions.Select(x => x.Name).Distinct().Count() > 1)
{
throw new ArgumentException("All definitions have to be overloads of the same method", nameof(definitions));
}
m_Overloads = definitions
.Select(d => new OperatorOverloadDocumentation(this, d, xmlDocsProvider))
.ToDictionary(x => x.MemberId);
Overloads = ReadOnlyCollectionAdapter.Create(m_Overloads.Values);
var operatorKinds = Overloads.Select(x => x.OperatorKind).Distinct().ToArray();
Kind = operatorKinds.Length == 1
? operatorKinds[0]
: throw new ArgumentException("Cannot combine overloads of different operators");
}
/// <summary>
/// Initializes a new instance of <see cref="ParameterDocumentation"/>.
/// </summary>
/// <param name="overloadDocumentation">The overload that defines the parameter.</param>
/// <param name="definition">The underlying Mono.Cecil definition of the parameter.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
internal ParameterDocumentation(OverloadDocumentation overloadDocumentation, ParameterDefinition definition, IXmlDocsProvider xmlDocsProvider)
{
OverloadDocumentation = overloadDocumentation ?? throw new ArgumentNullException(nameof(overloadDocumentation));
xmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
ParameterType = definition.ParameterType.ToTypeId();
Description = xmlDocsProvider.TryGetDocumentationComments(overloadDocumentation.MemberId)?.Parameters?.GetValueOrDefault(definition.Name);
}
/// <summary>
/// Initializes a new instance of <see cref="TypeDocumentation"/>.
/// </summary>
/// <param name="assemblyDocumentation">The documentation model of the assembly that defines the type.</param>
/// <param name="namespaceDocumentation">The documentation model of the type's namespace.</param>
/// <param name="definition">The type's underlying Mono.Cecil definition.</param>
/// <param name="xmlDocsProvider">The XML documentation provider to use for loading XML documentation comments.</param>
/// <param name="logger">The logger to use.</param>
internal TypeDocumentation(AssemblyDocumentation assemblyDocumentation,
NamespaceDocumentation namespaceDocumentation,
TypeDefinition definition,
IXmlDocsProvider xmlDocsProvider,
ILogger logger,
TypeDocumentation?declaringType)
{
TypeId = definition.ToTypeId();
DeclaringType = declaringType;
AssemblyDocumentation = assemblyDocumentation ?? throw new ArgumentNullException(nameof(assemblyDocumentation));
NamespaceDocumentation = namespaceDocumentation ?? throw new ArgumentNullException(nameof(namespaceDocumentation));
Definition = definition ?? throw new ArgumentNullException(nameof(definition));
m_XmlDocsProvider = xmlDocsProvider ?? throw new ArgumentNullException(nameof(xmlDocsProvider));
m_Logger = logger ?? throw new ArgumentNullException(nameof(logger));
m_Logger.LogDebug($"Loading documentation for type '{definition.FullName}'");
Kind = definition.Kind();
m_Logger.LogDebug("Loading fields");
m_Fields = definition.Fields
.Where(field => field.IsPublic && !field.Attributes.HasFlag(FieldAttributes.SpecialName))
.Select(field => new FieldDocumentation(this, field, xmlDocsProvider))
.ToDictionary(f => f.MemberId);
Fields = ReadOnlyCollectionAdapter.Create(m_Fields.Values);
m_Logger.LogDebug("Loading events");
m_Events = definition.Events
.Where(ev => (ev.AddMethod?.IsPublic == true || ev.RemoveMethod?.IsPublic == true))
.Select(e => new EventDocumentation(this, e, xmlDocsProvider))
.ToDictionary(e => e.MemberId);
Events = ReadOnlyCollectionAdapter.Create(m_Events.Values);
m_Logger.LogDebug("Loading properties");
m_Properties = definition.Properties
.Where(property => (property.GetMethod?.IsPublic == true || property.SetMethod?.IsPublic == true) && !property.HasParameters)
.Select(p => new PropertyDocumentation(this, p, xmlDocsProvider))
.ToDictionary(p => p.MemberId);
Properties = ReadOnlyCollectionAdapter.Create(m_Properties.Values);
m_Logger.LogDebug("Loading indexers");
m_Indexers = definition.Properties
.Where(property => (property.GetMethod?.IsPublic == true || property.SetMethod?.IsPublic == true) && property.HasParameters)
.GroupBy(p => p.Name)
.Select(group => new IndexerDocumentation(this, group, xmlDocsProvider))
.ToDictionary(indexer => indexer.Name);
Indexers = ReadOnlyCollectionAdapter.Create(m_Indexers.Values);
m_Logger.LogDebug("Loading constructors");
var ctors = definition.GetPublicConstrutors();
if (ctors.Any())
{
Constructors = new ConstructorDocumentation(this, ctors, xmlDocsProvider);
}
m_Logger.LogDebug("Loading methods");
m_Methods = definition.GetPublicMethods()
.Where(m => !m.IsOperator())
.GroupBy(x => x.Name)
.Select(group => new MethodDocumentation(this, group, xmlDocsProvider))
.ToDictionary(m => m.Name);
Methods = ReadOnlyCollectionAdapter.Create(m_Methods.Values);
m_Logger.LogDebug("Loading operator overloads");
m_Operators = definition.GetPublicMethods()
.GroupBy(x => x.GetOperatorKind())
.Where(group => group.Key.HasValue)
.Select(group => new OperatorDocumentation(this, group, xmlDocsProvider))
.ToDictionary(x => x.Kind);
Operators = ReadOnlyCollectionAdapter.Create(m_Operators.Values);
m_Logger.LogDebug("Loading inheritance hierarchy.");
InheritanceHierarchy = LoadInheritanceHierarchy();
m_Logger.LogDebug("Loading custom attributes");
Attributes = Definition
.GetCustomAttributes()
.Select(x => x.AttributeType.ToTypeId())
.ToArray();
m_Logger.LogDebug("Loading implemented interfaces");
ImplementedInterfaces = LoadImplementedInterfaces();
TypeParameters = LoadTypeParameters();
var documentationComments = m_XmlDocsProvider.TryGetDocumentationComments(MemberId);
Summary = documentationComments?.Summary ?? TextBlock.Empty;
Remarks = documentationComments?.Remarks ?? TextBlock.Empty;
SeeAlso = documentationComments?.SeeAlso?.AsReadOnlyList() ?? Array.Empty <SeeAlsoElement>();
Example = documentationComments?.Example ?? TextBlock.Empty;
CSharpDefinition = CSharpDefinitionFormatter.GetDefinition(definition);
IsObsolete = definition.IsObsolete(out var obsoleteMessage);
ObsoleteMessage = obsoleteMessage;
}
