private void ResolveCodeSource(XDocument doc, ITripleSlashCommentParserContext context)
{
foreach (XElement node in doc.XPathSelectElements("//code"))
{
var source = node.Attribute("source");
if (source == null || string.IsNullOrEmpty(source.Value))
{
continue;
}
if (context.Source == null || string.IsNullOrEmpty(context.Source.Path))
{
Logger.LogWarning($"Unable to get source file path for {node.ToString()}");
return;
}
var region = node.Attribute("region");
var path = source.Value;
if (!Path.IsPathRooted(path))
{
var basePath = !string.IsNullOrEmpty(context.CodeSourceBasePath) ? context.CodeSourceBasePath : Path.GetDirectoryName(Path.Combine(EnvironmentContext.BaseDirectory, context.Source.Path));
path = Path.Combine(basePath, path);
}
ResolveCodeSource(node, path, region?.Value);
}
}
public static TripleSlashCommentModel CreateModel(string xml, ITripleSlashCommentParserContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
if (string.IsNullOrEmpty(xml))
{
return(null);
}
// Quick turnaround for badly formed XML comment
if (xml.StartsWith("<!-- Badly formed XML comment ignored for member "))
{
Logger.LogWarning($"Invalid triple slash comment is ignored: {xml}");
return(null);
}
try
{
var model = new TripleSlashCommentModel(xml, context);
return(model);
}
catch (XmlException)
{
return(null);
}
}
private TripleSlashCommentModel(string xml, SyntaxLanguage language, ITripleSlashCommentParserContext context)
{
// Transform triple slash comment
XDocument doc = TripleSlashCommentTransformer.Transform(xml, language);
_context = context;
if (!context.PreserveRawInlineComments)
{
ResolveSeeCref(doc, context.AddReferenceDelegate, context.ResolveCRef);
ResolveSeeAlsoCref(doc, context.AddReferenceDelegate, context.ResolveCRef);
ResolveExceptionCref(doc, context.AddReferenceDelegate, context.ResolveCRef);
}
ResolveCodeSource(doc, context);
var nav = doc.CreateNavigator();
Summary = GetSummary(nav, context);
Remarks = GetRemarks(nav, context);
Returns = GetReturns(nav, context);
Exceptions = GetExceptions(nav, context);
Sees = GetSees(nav, context);
SeeAlsos = GetSeeAlsos(nav, context);
Examples = GetExamples(nav, context);
Parameters = GetParameters(nav, context);
TypeParameters = GetTypeParameters(nav, context);
IsInheritDoc = GetIsInheritDoc(nav, context);
}
private TripleSlashCommentModel(string xml, ITripleSlashCommentParserContext context)
{
// Normalize xml line ending before load into xml
XDocument doc = XDocument.Parse(xml, LoadOptions.SetLineInfo | LoadOptions.PreserveWhitespace);
if (!context.PreserveRawInlineComments)
{
ResolveSeeCref(doc, context.AddReferenceDelegate);
ResolveSeeAlsoCref(doc, context.AddReferenceDelegate);
ResolveParameterRef(doc);
}
var nav = doc.CreateNavigator();
_lines = doc.ToString().Split('\n');
Summary = GetSummary(nav, context);
Remarks = GetRemarks(nav, context);
Returns = GetReturns(nav, context);
Exceptions = GetExceptions(nav, context);
Sees = GetSees(nav, context);
SeeAlsos = GetSeeAlsos(nav, context);
Examples = GetExamples(nav, context);
Parameters = GetParameters(nav, context);
TypeParameters = GetTypeParameters(nav, context);
}
/// <summary>
/// Get summary node out from triple slash comments
/// </summary>
/// <param name="xml"></param>
/// <param name="normalize"></param>
/// <returns></returns>
/// <example>
/// <code> <see cref="Hello"/></code>
/// </example>
private static string GetSummary(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
// Resolve <see cref> to @ syntax
// Also support <seealso cref>
string selector = "/member/summary";
return(GetSingleNodeValue(nav, selector, context.Normalize));
}
private string GetReturns(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
// Resolve <see cref> to @ syntax
// Also support <seealso cref>
string selector = "/member/returns";
return(GetSingleNodeValue(nav, selector));
}
/// <summary>
/// To get `seealso` tags out
/// </summary>
/// <param name="xml"></param>
/// <param name="context"></param>
/// <returns></returns>
/// <seealso cref="WaitForChangedResult"/>
/// <seealso cref="http://google.com">ABCS</seealso>
private List <LinkInfo> GetSeeAlsos(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
var result = GetMultipleLinkInfo(nav, "/member/seealso").ToList();
if (result.Count == 0)
{
return(null);
}
return(result);
}
/// <summary>
/// To get `seealso` tags out
/// </summary>
/// <param name="xml"></param>
/// <param name="context"></param>
/// <returns></returns>
/// <seealso cref="WaitForChangedResult"/>
/// <seealso cref="http://google.com">ABCS</seealso>
private static List <CrefInfo> GetSeeAlsos(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
var result = GetMulitpleCrefInfo(nav, "/member/seealso", context.Normalize).ToList();
if (result.Count == 0)
{
return(null);
}
return(result);
}
/// <summary>
/// Get exceptions nodes out from triple slash comments
/// </summary>
/// <param name="xml"></param>
/// <param name="normalize"></param>
/// <returns></returns>
/// <exception cref="XmlException">This is a sample of exception node</exception>
private List <ExceptionInfo> GetExceptions(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
string selector = "/member/exception";
var result = GetMulitpleCrefInfo(nav, selector).ToList();
if (result.Count == 0)
{
return(null);
}
return(result);
}
public static void FeedComments(MetadataItem item, ITripleSlashCommentParserContext context)
{
if (!string.IsNullOrEmpty(item.RawComment))
{
var commentModel = TripleSlashCommentModel.CreateModel(item.RawComment, item.Language, context);
if (commentModel == null) return;
item.Summary = commentModel.Summary;
item.Remarks = commentModel.Remarks;
item.Exceptions = commentModel.Exceptions;
item.Sees = commentModel.Sees;
item.SeeAlsos = commentModel.SeeAlsos;
item.Examples = commentModel.Examples;
item.CommentModel = commentModel;
}
}
public static TripleSlashCommentModel CreateModel(string xml, ITripleSlashCommentParserContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
if (string.IsNullOrEmpty(xml))
{
return(null);
}
// Quick turnaround for badly formed XML comment
if (xml.StartsWith("<!-- Badly formed XML comment ignored for member "))
{
return(null);
}
try
{
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);
var nav = doc.CreateNavigator();
if (!context.PreserveRawInlineComments)
{
ResolveSeeCref(nav, string.Empty, context.AddReferenceDelegate);
ResolveSeeAlsoCref(nav, string.Empty, context.AddReferenceDelegate);
ResolveParameterRef(nav);
}
var model = new TripleSlashCommentModel();
model.Summary = GetSummary(nav, context);
model.Remarks = GetRemarks(nav, context);
model.Returns = GetReturns(nav, context);
model.Exceptions = GetExceptions(nav, context);
model.Sees = GetSees(nav, context);
model.SeeAlsos = GetSeeAlsos(nav, context);
model.Examples = GetExamples(nav, context);
model.Parameters = GetParameters(nav, context);
model.TypeParameters = GetTypeParameters(nav, context);
return(model);
}
catch (XmlException)
{
return(null);
}
}
public static void FeedComments(MetadataItem item, ITripleSlashCommentParserContext context)
{
if (!string.IsNullOrEmpty(item.RawComment))
{
var commentModel = TripleSlashCommentModel.CreateModel(item.RawComment, item.Language, context);
if (commentModel == null)
{
return;
}
item.Summary = commentModel.Summary;
item.Remarks = commentModel.Remarks;
item.Exceptions = commentModel.Exceptions;
item.Sees = commentModel.Sees;
item.SeeAlsos = commentModel.SeeAlsos;
item.Examples = commentModel.Examples;
item.CommentModel = commentModel;
}
}
private bool GetIsInheritDoc(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
var node = nav.SelectSingleNode("/member/inheritdoc");
if (node == null)
{
return(false);
}
if (node.HasAttributes)
{
//The Sandcastle implementation of <inheritdoc /> supports two attributes: 'cref' and 'select'.
//These attributes allow changing the source of the inherited doc and controlling what is inherited.
//Until these attributes are supported, ignoring inheritdoc elements with attributes, so as not to misinterpret them.
Logger.LogWarning("Attributes on <inheritdoc /> elements are not supported; inheritdoc element will be ignored.");
return(false);
}
return(true);
}
private string GetInheritDoc(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
var node = nav.SelectSingleNode("/member/inheritdoc");
if (node == null)
{
return(null);
}
if (node.HasAttributes)
{
// The Sandcastle implementation of <inheritdoc /> supports two attributes: 'cref' and 'select'.
// These attributes allow changing the source of the inherited doc and controlling what is inherited.
// Only cref is supported currently
var cRef = node.GetAttribute("cref", node.NamespaceURI);
if (!string.IsNullOrEmpty(cRef))
{
// Strict check is needed as value could be an invalid href,
// e.g. !:Dictionary<TKey, string> when user manually changed the intellisensed generic type
var match = CommentIdRegex.Match(cRef);
if (match.Success)
{
var id = match.Groups["id"].Value;
var type = match.Groups["type"].Value;
if (type == "Overload")
{
id += '*';
}
context.AddReferenceDelegate?.Invoke(id, cRef);
return(id);
}
}
else
{
Logger.LogWarning("Unsupported attribute on <inheritdoc />; inheritdoc element will be ignored.");
return(null);
}
}
// Default inheritdoc (no explicit reference)
return(string.Empty);
}
public static TripleSlashCommentModel CreateModel(string xml, SyntaxLanguage language, ITripleSlashCommentParserContext context)
{
if (context == null) throw new ArgumentNullException(nameof(context));
if (string.IsNullOrEmpty(xml)) return null;
// Quick turnaround for badly formed XML comment
if (xml.StartsWith("<!-- Badly formed XML comment ignored for member "))
{
Logger.LogWarning($"Invalid triple slash comment is ignored: {xml}");
return null;
}
try
{
var model = new TripleSlashCommentModel(xml, language, context);
return model;
}
catch (XmlException)
{
return null;
}
}
private TripleSlashCommentModel(string xml, SyntaxLanguage language, ITripleSlashCommentParserContext context)
{
// Transform triple slash comment
XDocument doc = _transformer.Transform(xml, language);
_context = context;
if (!context.PreserveRawInlineComments)
{
ResolveSeeCref(doc, context.AddReferenceDelegate);
ResolveSeeAlsoCref(doc, context.AddReferenceDelegate);
}
var nav = doc.CreateNavigator();
Summary = GetSummary(nav, context);
Remarks = GetRemarks(nav, context);
Returns = GetReturns(nav, context);
Exceptions = GetExceptions(nav, context);
Sees = GetSees(nav, context);
SeeAlsos = GetSeeAlsos(nav, context);
Examples = GetExamples(nav, context);
Parameters = GetParameters(nav, context);
TypeParameters = GetTypeParameters(nav, context);
}
public static TripleSlashCommentModel CreateModel(string xml, ITripleSlashCommentParserContext context)
{
if (context == null) throw new ArgumentNullException(nameof(context));
if (string.IsNullOrEmpty(xml)) return null;
// Quick turnaround for badly formed XML comment
if (xml.StartsWith("<!-- Badly formed XML comment ignored for member ")) return null;
try
{
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);
var nav = doc.CreateNavigator();
if (!context.PreserveRawInlineComments)
{
ResolveSeeCref(nav, string.Empty, context.AddReferenceDelegate);
ResolveSeeAlsoCref(nav, string.Empty, context.AddReferenceDelegate);
ResolveParameterRef(nav);
}
var model = new TripleSlashCommentModel();
model.Summary = GetSummary(nav, context);
model.Remarks = GetRemarks(nav, context);
model.Returns = GetReturns(nav, context);
model.Exceptions = GetExceptions(nav, context);
model.Sees = GetSees(nav, context);
model.SeeAlsos = GetSeeAlsos(nav, context);
model.Examples = GetExamples(nav, context);
model.Parameters = GetParameters(nav, context);
model.TypeParameters = GetTypeParameters(nav, context);
return model;
}
catch (XmlException)
{
return null;
}
}
private static Dictionary<string, string> GetTypeParameters(XPathNavigator navigator, ITripleSlashCommentParserContext context)
{
return GetListContent(navigator, "/member/typeparam", "type parameter", context);
}
private static Dictionary<string, string> GetListContent(XPathNavigator navigator, string xpath, string contentType, ITripleSlashCommentParserContext context)
{
var iterator = navigator.Select(xpath);
var result = new Dictionary<string, string>();
if (iterator == null) return result;
foreach (XPathNavigator nav in iterator)
{
string name = nav.GetAttribute("name", string.Empty);
string description = nav.InnerXml;
if (context.Normalize) description = NormalizeContentFromTripleSlashComment(description);
if (!string.IsNullOrEmpty(name))
{
if (result.ContainsKey(name))
{
string path = context.Source.Remote != null ? Path.Combine(context.Source.Remote.LocalWorkingDirectory, context.Source.Remote.RelativePath) : context.Source.Path;
Logger.LogWarning($"Duplicate {contentType} '{name}' found in comments, the latter one is ignored.", null, path.ToDisplayPath(), context.Source.StartLine.ToString());
}
else
{
result.Add(name, description);
}
}
}
return result;
}
/// <summary>
/// To get `example` tags out
/// </summary>
/// <param name="xml"></param>
/// <param name="context"></param>
/// <returns></returns>
/// <example>
/// This sample shows how to call the <see cref="GetExceptions(string, ITripleSlashCommentParserContext)"/> method.
/// <code>
/// class TestClass
/// {
/// static int Main()
/// {
/// return GetExceptions(null, null).Count();
/// }
/// }
/// </code>
/// </example>
private static List<string> GetExamples(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
// Resolve <see cref> to @ syntax
// Also support <seealso cref>
return GetMultipleExampleNodes(nav, "/member/example", context.Normalize).ToList();
}
/// <summary>
/// To get `seealso` tags out
/// </summary>
/// <param name="xml"></param>
/// <param name="context"></param>
/// <returns></returns>
/// <seealso cref="WaitForChangedResult"/>
/// <seealso cref="http://google.com">ABCS</seealso>
private static List<CrefInfo> GetSeeAlsos(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
var result = GetMulitpleCrefInfo(nav, "/member/seealso", context.Normalize).ToList();
if (result.Count == 0) return null;
return result;
}
/// <summary>
/// Get exceptions nodes out from triple slash comments
/// </summary>
/// <param name="xml"></param>
/// <param name="normalize"></param>
/// <returns></returns>
/// <exception cref="XmlException">This is a sample of exception node</exception>
private static List<CrefInfo> GetExceptions(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
string selector = "/member/exception";
var result = GetMulitpleCrefInfo(nav, selector, context.Normalize).ToList();
if (result.Count == 0) return null;
return result;
}
public static ApiParameter GetParameterDescription(ISymbol symbol, MetadataItem item, string id, bool isReturn, ITripleSlashCommentParserContext context)
{
string comment = isReturn ? item.CommentModel?.Returns : item.CommentModel?.GetParameter(symbol.Name);
return new ApiParameter
{
Name = isReturn ? null : symbol.Name,
Type = id,
Description = comment,
};
}
/// <summary>
/// To get `seealso` tags out
/// </summary>
/// <param name="xml"></param>
/// <param name="context"></param>
/// <returns></returns>
/// <seealso cref="WaitForChangedResult"/>
/// <seealso cref="http://google.com">ABCS</seealso>
private List<LinkInfo> GetSeeAlsos(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
var result = GetMultipleLinkInfo(nav, "/member/seealso").ToList();
if (result.Count == 0) return null;
return result;
}
/// <summary>
/// Get summary node out from triple slash comments
/// </summary>
/// <param name="xml"></param>
/// <param name="normalize"></param>
/// <returns></returns>
/// <example>
/// <code> <see cref="Hello"/></code>
/// </example>
private string GetSummary(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
// Resolve <see cref> to @ syntax
// Also support <seealso cref>
string selector = "/member/summary";
return GetSingleNodeValue(nav, selector);
}
private Dictionary <string, string> GetListContent(XPathNavigator navigator, string xpath, string contentType, ITripleSlashCommentParserContext context)
{
var iterator = navigator.Select(xpath);
var result = new Dictionary <string, string>();
if (iterator == null)
{
return(result);
}
foreach (XPathNavigator nav in iterator)
{
string name = nav.GetAttribute("name", string.Empty);
string description = GetXmlValue(nav);
if (!string.IsNullOrEmpty(name))
{
if (result.ContainsKey(name))
{
string path = context.Source.Remote != null?Path.Combine(EnvironmentContext.BaseDirectory, context.Source.Remote.RelativePath) : context.Source.Path;
Logger.LogWarning($"Duplicate {contentType} '{name}' found in comments, the latter one is ignored.", null, StringExtension.ToDisplayPath(path), context.Source.StartLine.ToString());
}
else
{
result.Add(name, description);
}
}
}
return(result);
}
public static ApiParameter GetTypeParameterDescription(ITypeParameterSymbol symbol, MetadataItem item, ITripleSlashCommentParserContext context)
{
string comment = item.CommentModel?.GetTypeParameter(symbol.Name);
return new ApiParameter
{
Name = symbol.Name,
Description = comment,
};
}
/// <summary>
/// Get remarks node out from triple slash comments
/// </summary>
/// <remarks>
/// <para>This is a sample of exception node</para>
/// </remarks>
/// <param name="xml"></param>
/// <param name="normalize"></param>
/// <returns></returns>
private static string GetRemarks(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
string selector = "/member/remarks";
return GetSingleNodeValue(nav, selector, context.Normalize);
}
/// <summary>
/// Get remarks node out from triple slash comments
/// </summary>
/// <remarks>
/// <para>This is a sample of exception node</para>
/// </remarks>
/// <param name="xml"></param>
/// <param name="normalize"></param>
/// <returns></returns>
private string GetRemarks(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
string selector = "/member/remarks";
return(GetSingleNodeValue(nav, selector));
}
private static string GetReturns(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
// Resolve <see cref> to @ syntax
// Also support <seealso cref>
string selector = "/member/returns";
return GetSingleNodeValue(nav, selector, context.Normalize);
}
public static ApiParameter GetParameterDescription(ISymbol symbol, MetadataItem item, string id, bool isReturn, ITripleSlashCommentParserContext context)
{
string comment = isReturn ? item.CommentModel?.Returns : item.CommentModel?.GetParameter(symbol.Name);
return(new ApiParameter
{
Name = isReturn ? null : symbol.Name,
Type = id,
Description = comment,
});
}
public static Dictionary<string, string> GetTypeParameters(XPathNavigator navigator, ITripleSlashCommentParserContext context)
{
var iterator = navigator.Select("/member/typeparam");
var result = new Dictionary<string, string>();
if (iterator == null) return result;
foreach (XPathNavigator nav in iterator)
{
string name = nav.GetAttribute("name", string.Empty);
string description = nav.Value;
if (context.Normalize) description = NormalizeContentFromTripleSlashComment(description);
if (!string.IsNullOrEmpty(name)) result.Add(name, description);
}
return result;
}
/// <summary>
/// To get `example` tags out
/// </summary>
/// <param name="xml"></param>
/// <param name="context"></param>
/// <returns></returns>
/// <example>
/// This sample shows how to call the <see cref="GetExceptions(string, ITripleSlashCommentParserContext)"/> method.
/// <code>
/// class TestClass
/// {
/// static int Main()
/// {
/// return GetExceptions(null, null).Count();
/// }
/// }
/// </code>
/// </example>
private List <string> GetExamples(XPathNavigator nav, ITripleSlashCommentParserContext context)
{
// Resolve <see cref> to @ syntax
// Also support <seealso cref>
return(GetMultipleExampleNodes(nav, "/member/example").ToList());
}
public static ApiParameter GetTypeParameterDescription(ITypeParameterSymbol symbol, MetadataItem item, ITripleSlashCommentParserContext context)
{
string comment = item.CommentModel?.GetTypeParameter(symbol.Name);
return(new ApiParameter
{
Name = symbol.Name,
Description = comment,
});
}
private Dictionary <string, string> GetTypeParameters(XPathNavigator navigator, ITripleSlashCommentParserContext context)
{
return(GetListContent(navigator, "/member/typeparam", "type parameter", context));
}
public static Dictionary <string, string> GetTypeParameters(XPathNavigator navigator, ITripleSlashCommentParserContext context)
{
var iterator = navigator.Select("/member/typeparam");
var result = new Dictionary <string, string>();
if (iterator == null)
{
return(result);
}
foreach (XPathNavigator nav in iterator)
{
string name = nav.GetAttribute("name", string.Empty);
string description = nav.Value;
if (context.Normalize)
{
description = NormalizeContentFromTripleSlashComment(description);
}
if (!string.IsNullOrEmpty(name))
{
result.Add(name, description);
}
}
return(result);
}
