private void ReadExceptionElement(XElement element, MemberElement member)
{
var cref = element.Attribute("cref")?.Value;
if (!TryParseMemberId(cref, out var memberId))
{
return;
}
if (memberId is TypeId typeId)
{
member.Exceptions.Add(new ExceptionElement(typeId, ReadTextBlock(element)));
}
else
{
m_Logger.LogWarning($"Unexpected member id '{cref}' in 'exception' element. " +
$"Expected id of type {nameof(TypeId)} but was {memberId!.GetType().Name}. " +
$"Ignoring exception element.");
}
}
/// <summary>
/// Reads all supported documentation elements and adds it to the specified member.
/// </summary>
/// <remarks>
/// Member is <c>internal</c> for testing purposes only.
/// </remarks>
internal void ReadMemberContent(XElement xml, MemberElement member)
{
foreach (var element in xml.Elements())
{
var elementName = element.Name.LocalName;
m_Logger.LogDebug($"Reading XML documentation element '{elementName}'");
switch (elementName)
{
case "summary":
member.Summary = ReadTextBlock(element);
break;
case "remarks":
member.Remarks = ReadTextBlock(element);
break;
case "example":
member.Example = ReadTextBlock(element);
break;
case "param":
{
if (element.TryGetAttributeValue("name", out var name))
{
member.Parameters.Add(name !, ReadTextBlock(element));
}
}
break;
case "typeparam":
{
if (element.TryGetAttributeValue("name", out var name))
{
member.TypeParameters.Add(name !, ReadTextBlock(element));
}
}
break;
case "seealso":
{
// <seealso /> allows adding links to the documentation
//
// - using <seealso cref="..." /> a link to other assembly members
// can be inserted (supported by Visual Studio)
// - using <seealso href="..." /> a link to an external resource,
// typically a website can be specified (unofficial extension, not supported by VS)
//
// If both cref and href attributes are present, href is ignored
//
if (element.TryGetAttributeValue("cref", out var cref))
{
if (TryParseMemberId(cref, out var memberId))
{
member.SeeAlso.Add(new SeeAlsoElement(memberId !, ReadTextBlock(element)));
}
}
else if (element.TryGetAttributeValue("href", out var href))
{
if (Uri.TryCreate(href, UriKind.Absolute, out var target))
{
member.SeeAlso.Add(new SeeAlsoElement(target, ReadTextBlock(element)));
}
}
}
break;
case "exception":
ReadExceptionElement(element, member);
break;
case "value":
member.Value = ReadTextBlock(element);
break;
case "returns":
member.Returns = ReadTextBlock(element);
break;
// ignore unknown elements
default:
m_Logger.LogWarning($"Encountered unknown element '{elementName}'. Element will be ignored.");
break;
}
}
}
