private void RenderReturnsBlock(System.Xml.XmlWriter writer, XmlCodeComment comment)
{
TypeRef returnTypeRef = _member.GetReturnType();
if (returnTypeRef == WellKnownTypeDef.Void)
{
return;
}
writer.WriteStartElement("return");
// write the details of the type and link details if available
writer.WriteStartElement("type");
TypeDef foundEntry = _member.Assembly.FindType(returnTypeRef.Namespace, returnTypeRef.Name);
writer.WriteAttributeString("name", returnTypeRef.GetDisplayName(false));
if (foundEntry != null)
{
writer.WriteAttributeString("key", foundEntry.GetGloballyUniqueId().ToString());
writer.WriteAttributeString("cref", CRefPath.Create(foundEntry).ToString());
}
writer.WriteEndElement();
// output the returns comment xml element if available
if (comment != XmlCodeComment.Empty)
{
RenderXmlBlock(writer, comment.Elements.Find(currentBlock => currentBlock is ReturnsXmlCodeElement));
}
writer.WriteEndElement();
}
private void WriteEntry(System.Xml.XmlWriter writer, ReflectedMember entryMember, string displayName, string type)
{
CRefPath currentPath = CRefPath.Create(entryMember);
XmlCodeComment currentComment = this._xmlComments.GetComment(currentPath);
writer.WriteStartElement("entry");
writer.WriteAttributeString("id", entryMember.GetGloballyUniqueId().ToString());
writer.WriteAttributeString("subId", string.Empty);
writer.WriteAttributeString("type", type);
writer.WriteAttributeString("visibility", ReflectionHelper.GetVisibility(entryMember));
writer.WriteAttributeString("cref", currentPath.ToString());
writer.WriteStartElement("name");
writer.WriteString(displayName);
writer.WriteEndElement();
// find and output the summary
if (currentComment != XmlCodeComment.Empty && currentComment.Elements != null)
{
XmlCodeElement summary = currentComment.Elements.Find(currentBlock => currentBlock is SummaryXmlCodeElement);
if (summary != null)
{
Serialize(summary, writer);
}
}
writer.WriteEndElement();
}
/// <summary>
/// Renders the method XML to the <paramref name="writer."/>
/// </summary>
/// <param name="writer">The open valid writer to write to.</param>
public override void Render(System.Xml.XmlWriter writer)
{
CRefPath crefPath = new CRefPath(_member);
XmlCodeComment comment = _xmlComments.GetComment(crefPath);
string displayName = _member.GetDisplayName(false);
writer.WriteStartElement("member");
writer.WriteAttributeString("id", AssociatedEntry.Key.ToString());
writer.WriteAttributeString("subId", AssociatedEntry.SubKey);
writer.WriteAttributeString("type", ReflectionHelper.GetType(_member));
writer.WriteAttributeString("cref", crefPath.ToString());
writer.WriteStartElement("name");
writer.WriteAttributeString("safename", Exporter.CreateSafeName(displayName));
writer.WriteString(_member.GetDisplayName(false));
writer.WriteEndElement();
writer.WriteStartElement("namespace");
Entry namespaceEntry = AssociatedEntry.FindNamespace(_member.Type.Namespace);
writer.WriteAttributeString("id", namespaceEntry.Key.ToString());
writer.WriteAttributeString("name", namespaceEntry.SubKey);
writer.WriteAttributeString("cref", $"N:{_member.Type.Namespace}");
writer.WriteString(_member.Type.Namespace);
writer.WriteEndElement();
writer.WriteStartElement("assembly");
writer.WriteAttributeString("file", System.IO.Path.GetFileName(_member.Assembly.FileName));
writer.WriteString(_member.Assembly.Name);
writer.WriteEndElement();
if (_member.IsGeneric)
{
RenderGenericTypeParameters(_member.GetGenericTypes(), writer, comment);
}
RenderParameters(writer, comment);
RenderExceptionBlock(_member, writer, comment);
RenderPermissionBlock(_member, writer, comment);
if (comment != XmlCodeComment.Empty)
{
RenderXmlBlock(writer, comment.Elements.Find(currentBlock => currentBlock is SummaryXmlCodeElement));
}
RenderSyntaxBlocks(_member, writer);
RenderReturnsBlock(writer, comment);
if (comment != XmlCodeComment.Empty)
{
RenderXmlBlock(writer, comment.Elements.Find(currentBlock => currentBlock is RemarksXmlCodeElement));
RenderXmlBlock(writer, comment.Elements.Find(currentBlock => currentBlock is ExampleXmlCodeElement));
RenderXmlBlock(writer, comment.Elements.Find(currentBlock => currentBlock is SeeAlsoXmlCodeElement));
}
RenderSeeAlsoBlock(_member, writer, comment);
writer.WriteEndElement();
}
public void WhenPassedNull_GetComment_ReturnsEmpty()
{
XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");
SetFileExistsAndLoadXml(commentFile);
XmlCodeComment result = commentFile.GetComment(null);
Assert.AreSame(XmlCodeComment.Empty, result);
}
public void WhenNotLoaded_GetComment_ReturnsEmpty()
{
XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");
_fileSystem.Setup(p => p.FileExists(It.IsAny <string>())).Returns(true);
CRefPath crefPath = CRefPath.Parse("T:Namespace.TypeName");
XmlCodeComment result = commentFile.GetComment(crefPath);
Assert.AreSame(XmlCodeComment.Empty, result);
}
public void WhenCRefValidButNoData_GetComment_ReturnsEmpty()
{
XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");
SetFileExistsAndLoadXml(commentFile);
CRefPath crefPath = CRefPath.Parse("T:Nowhere.DoesntExist");
XmlCodeComment result = commentFile.GetComment(crefPath);
Assert.AreSame(XmlCodeComment.Empty, result);
}
public void WhenCRefInvalid_GetSummary_ReturnsEmpty()
{
XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");
SetFileExistsAndLoadXml(commentFile);
CRefPath crefPath = CRefPath.Parse("T:Nothing");
XmlCodeComment result = commentFile.GetSummary(crefPath);
Assert.AreSame(XmlCodeComment.Empty, result);
}
public void WhenCRefValid_GetSummary_ReturnsSummary()
{
XmlCommentFile commentFile = CreateXmlCommentFile("Myfile.xml");
CRefPath crefPath = CRefPath.Parse("T:Namespace.MyType");
SetFileExistsAndLoadXml(commentFile);
XmlCodeComment result = commentFile.GetSummary(crefPath);
Assert.AreEqual("Summary text", result.Elements[0].Text);
}
public void WhenCRefIsValid_GetComment_GetsCorrectComment()
{
XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");
SetFileExistsAndLoadXml(commentFile);
CRefPath crefPath = CRefPath.Parse("T:Namespace.MyType");
XmlCodeComment result = commentFile.GetComment(crefPath);
Assert.AreNotSame(XmlCodeComment.Empty, result);
Assert.AreEqual(1, result.Elements.Count);
}
private void WriteAsText(StringBuilder builder, XmlCodeComment comment)
{
builder.Append("{");
builder.Append(comment.Element.ToString());
builder.Append(":");
builder.Append(comment.Text);
foreach (XmlCodeElement element in comment.Elements)
{
this.WriteAsText(builder, element);
}
builder.Append("}");
}
protected Block GetSummaryFor(ICommentSource comments, AssemblyDef assembly, CRefPath element)
{
Block constructorSummary = null;
XmlCodeComment comment = comments.GetSummary(element);
List <Block> constructorComments = Elements.Parser.Parse(assembly, comment);
if (constructorComments != null && constructorComments.Count > 0)
{
constructorSummary = constructorComments.First();
}
return(constructorSummary);
}
public void WhenCRefIsErrorPath_GetComment_ReturnsEmpty()
{
XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");
SetFileExistsAndLoadXml(commentFile);
CRefPath crefPath = new CRefPath();
crefPath.PathType = CRefTypes.Error;
XmlCodeComment result = commentFile.GetComment(crefPath);
Assert.AreSame(XmlCodeComment.Empty, result);
}
private void RenderParameters(System.Xml.XmlWriter writer, XmlCodeComment comment)
{
if (_member.Parameters.Count > 0)
{
writer.WriteStartElement("parameters");
for (int i = 0; i < _member.Parameters.Count; i++)
{
if (_member.Parameters[i].Sequence == 0)
{
continue;
}
TypeRef parameterType = _member.ResolveParameter(_member.Parameters[i].Sequence);
TypeDef foundEntry = _member.Assembly.FindType(parameterType.Namespace, parameterType.Name);
writer.WriteStartElement("parameter");
writer.WriteAttributeString("name", _member.Parameters[i].Name);
writer.WriteStartElement("type");
if (foundEntry != null)
{
writer.WriteAttributeString("key", foundEntry.GetGloballyUniqueId().ToString());
writer.WriteAttributeString("cref", CRefPath.Create(foundEntry).ToString());
}
writer.WriteString(parameterType.GetDisplayName(false));
writer.WriteEndElement(); // type
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement paramEntry = comment.Elements.Find(currentBlock =>
currentBlock is ParamXmlCodeElement &&
((ParamXmlCodeElement)currentBlock).Name == _member.Parameters[i].Name);
if (paramEntry != null)
{
writer.WriteStartElement("description");
ParamXmlCodeElement paraElement = (ParamXmlCodeElement)paramEntry;
for (int j = 0; j < paraElement.Elements.Count; j++)
{
Serialize(paraElement.Elements[j], writer);
}
writer.WriteEndElement();
}
}
writer.WriteEndElement(); // parameter
}
writer.WriteEndElement();
}
}
/// <summary>
/// Converts the
/// </summary>
/// <param name="assembly">The assembly associated with the member being documented.</param>
/// <param name="file">The xml comment file to read the member comments.</param>
/// <param name="crefPathToMember">The CRef path to the Member.</param>
/// <returns>A string containing the documentation.</returns>
public static string Convert(AssemblyDef assembly, ICommentSource file, CRefPath crefPathToMember)
{
StringBuilder text = new StringBuilder();
XmlCodeComment comment = file.GetComment(crefPathToMember);
if (comment != XmlCodeComment.Empty)
{
SummaryXmlCodeElement summary = (SummaryXmlCodeElement)comment.Elements.Find(o => o is SummaryXmlCodeElement);
if (summary != null)
{
foreach (XmlCodeElement current in summary.Elements)
{
PlainTextSummaryConverter.ConvertElement(assembly, current, text);
}
}
}
return(text.ToString());
}
/// <summary>
/// Attempts to get the summary comment for the element and if that is not defined it will
/// search for the value element instead.
/// </summary>
private Block GetXmlComments(FieldDef currentField, CRefPath crefPath)
{
Block summary = null;
XmlCodeComment comment = _xmlComments.GetSummary(crefPath);
if (comment == XmlCodeComment.Empty)
{
comment = _xmlComments.GetValue(crefPath);
}
List <Block> parsedBlocks = Parser.Parse(currentField.Assembly, comment);
if (parsedBlocks != null && parsedBlocks.Count > 0)
{
summary = parsedBlocks[0];
}
return(summary);
}
/// <summary>
/// Renders the XML for the namespace to the specified <paramref name="writer"/>.
/// </summary>
/// <param name="writer">The writer.</param>
public override void Render(System.Xml.XmlWriter writer)
{
writer.WriteStartElement("namespace");
writer.WriteAttributeString("id", AssociatedEntry.Key.ToString());
writer.WriteAttributeString("subId", AssociatedEntry.SubKey);
WriteCref(AssociatedEntry, writer);
writer.WriteStartElement("name");
writer.WriteAttributeString("safename", Exporter.CreateSafeName(_member.Key));
writer.WriteString($"{_member.Key} Namespace");
writer.WriteEndElement();
foreach (Entry current in AssociatedEntry.Children)
{
writer.WriteStartElement("parent");
writer.WriteAttributeString("name", current.Name);
writer.WriteAttributeString("key", current.Key.ToString());
writer.WriteAttributeString("type", ReflectionHelper.GetType((TypeDef)current.Item));
writer.WriteAttributeString("visibility", ReflectionHelper.GetVisibility(current.Item));
WriteCref(current, writer);
// write the summary text for the current member
XmlCodeComment comment = _xmlComments.GetComment(new CRefPath((TypeDef)current.Item));
if (comment != null && comment.Elements != null)
{
SummaryXmlCodeElement summary = comment.Elements.Find(
p => p is SummaryXmlCodeElement
) as SummaryXmlCodeElement;
if (summary != null)
{
Serialize(summary, writer);
}
}
writer.WriteEndElement();
}
writer.WriteEndElement();
}
/// <summary>
/// Parses the XML Code comments from the <paramref name="comment"/> provided.
/// </summary>
/// <param name="assembly">The assembly the member is defined in.</param>
/// <param name="comment">The parsed XmlCodeComment to parse.</param>
/// <returns>A List of blocks for the members commentary.</returns>
/// <exception cref="Model.XmlCommentParserException">
/// Thrown when an error occurs when parsing WPF Document elements from the provided
/// <paramref name="comment"/>.
/// </exception>
public static List <Block> Parse(AssemblyDef assembly, XmlCodeComment comment)
{
if (assembly == null)
{
throw new ArgumentNullException("assembly");
}
List <Block> blocks = new List <Block>();
try
{
if (comment != null && comment != XmlCodeComment.Empty && comment.Elements.Count > 0)
{
blocks = Parser.Parse(assembly, (XmlContainerCodeElement)comment);
}
}
catch (Exception ex)
{
throw new Model.XmlCommentParserException(comment, "An error converting the comment to document elements.", ex);
}
return(blocks);
}
public override void Render(System.Xml.XmlWriter writer)
{
CRefPath crefPath = new CRefPath(_member);
XmlCodeComment comment = _xmlComments.GetComment(crefPath);
string displayName = new DisplayNameSignitureConvertor(_member, false, true).Convert();
writer.WriteStartElement("member");
writer.WriteAttributeString("id", AssociatedEntry.Key.ToString());
writer.WriteAttributeString("subId", AssociatedEntry.SubKey);
writer.WriteAttributeString("type", ReflectionHelper.GetType(_member));
WriteCref(AssociatedEntry, writer);
writer.WriteStartElement("name");
writer.WriteAttributeString("safename", displayName);
writer.WriteString(displayName);
writer.WriteEndElement();
writer.WriteStartElement("namespace");
Entry namespaceEntry = AssociatedEntry.FindNamespace(_member.OwningType.Namespace);
writer.WriteAttributeString("id", namespaceEntry.Key.ToString());
writer.WriteAttributeString("name", namespaceEntry.SubKey);
writer.WriteAttributeString("cref", $"N:{_member.OwningType.Namespace}");
writer.WriteString(_member.OwningType.Namespace);
writer.WriteEndElement();
writer.WriteStartElement("assembly");
writer.WriteAttributeString("file", System.IO.Path.GetFileName(_member.Assembly.FileName));
writer.WriteString(_member.Assembly.Name);
writer.WriteEndElement();
// find and output the summary
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement summary = comment.Elements.Find(currentBlock => currentBlock is SummaryXmlCodeElement);
if (summary != null)
{
Serialize(summary, writer);
}
}
RenderExceptionBlock(_member, writer, comment);
RenderPermissionBlock(_member, writer, comment);
RenderSyntaxBlocks(_member, writer);
MethodDef internalMethod = _member.Getter == null ? _member.Setter : _member.Getter;
if (_member.IsIndexer() && internalMethod.Parameters.Count > 0)
{
writer.WriteStartElement("parameters");
for (int i = 0; i < internalMethod.Parameters.Count; i++)
{
if (internalMethod.Parameters[i].Sequence == 0)
{
continue;
}
TypeRef parameterType = internalMethod.ResolveParameter(internalMethod.Parameters[i].Sequence);
TypeDef foundEntry = _member.Assembly.FindType(parameterType.Namespace, parameterType.Name);
writer.WriteStartElement("parameter");
writer.WriteAttributeString("name", internalMethod.Parameters[i].Name);
writer.WriteStartElement("type");
if (foundEntry != null)
{
writer.WriteAttributeString("key", foundEntry.GetGloballyUniqueId().ToString());
writer.WriteAttributeString("cref", CRefPath.Create(foundEntry).ToString());
}
writer.WriteString(parameterType.GetDisplayName(false));
writer.WriteEndElement(); // type
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement paramEntry = comment.Elements.Find(currentBlock =>
currentBlock is ParamXmlCodeElement &&
((ParamXmlCodeElement)currentBlock).Name == internalMethod.Parameters[i].Name);
if (paramEntry != null)
{
writer.WriteStartElement("description");
ParamXmlCodeElement paraElement = (ParamXmlCodeElement)paramEntry;
for (int j = 0; j < paraElement.Elements.Count; j++)
{
Serialize(paraElement.Elements[j], writer);
}
writer.WriteEndElement();
}
}
writer.WriteEndElement(); // parameter
}
writer.WriteEndElement();
}
// find and output the value
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is ValueXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
// find and output the remarks
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is RemarksXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
// find and output the examples
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is ExampleXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
RenderSeeAlsoBlock(_member, writer, comment);
writer.WriteEndElement();
}
/// <summary>
/// Initialises a new instance of the XmlCommentParserException.
/// </summary>
/// <param name="comment">The XmlCodeCommnet being parsed when the error occurred.</param>
/// <param name="innerException">The thrown exception.</param>
public XmlCommentParserException(XmlCodeComment comment, Exception innerException)
: base(string.Empty, innerException)
{
this.Comment = comment;
}
/// <summary>
/// Initialises a new instance of the XmlCommentParserException.
/// </summary>
/// <param name="comment">The XmlCodeCommnet being parsed when the error occurred.</param>
/// <param name="message">Message describing the error.</param>
/// <param name="innerException">The thrown exception.</param>
public XmlCommentParserException(XmlCodeComment comment, string message, Exception innerException)
: base(message, innerException)
{
this.Comment = comment;
}
public override void Render(System.Xml.XmlWriter writer)
{
CRefPath crefPath = new CRefPath(_member);
XmlCodeComment comment = _xmlComments.GetComment(crefPath);
writer.WriteStartElement("member");
writer.WriteAttributeString("id", AssociatedEntry.Key.ToString());
writer.WriteAttributeString("subId", AssociatedEntry.SubKey);
writer.WriteAttributeString("type", ReflectionHelper.GetType(_member));
writer.WriteAttributeString("cref", crefPath.ToString());
writer.WriteStartElement("name");
writer.WriteAttributeString("safename", Exporter.CreateSafeName(_member.Name));
writer.WriteString(_member.Name);
writer.WriteEndElement();
writer.WriteStartElement("namespace");
Entry namespaceEntry = this.AssociatedEntry.FindNamespace(_member.Type.Namespace);
writer.WriteAttributeString("id", namespaceEntry.Key.ToString());
writer.WriteAttributeString("name", namespaceEntry.SubKey);
writer.WriteAttributeString("cref", $"N:{_member.Type.Namespace}");
writer.WriteString(_member.Type.Namespace);
writer.WriteEndElement();
writer.WriteStartElement("assembly");
writer.WriteAttributeString("file", System.IO.Path.GetFileName(_member.Assembly.FileName));
writer.WriteString(_member.Assembly.Name);
writer.WriteEndElement();
// find and output the summary
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement summary = comment.Elements.Find(currentBlock => currentBlock is SummaryXmlCodeElement);
if (summary != null)
{
Serialize(summary, writer);
}
}
this.RenderPermissionBlock(_member, writer, comment);
this.RenderSyntaxBlocks(_member, writer);
// find and output the value
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is ValueXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
// find and output the summary
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is RemarksXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
// find and output the examples
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is ExampleXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
RenderSeeAlsoBlock(_member, writer, comment);
writer.WriteEndElement();
}
/// <summary>
/// Renders the generic types in XML.
/// </summary>
/// <param name="genericTypes">The generic types to render.</param>
/// <param name="writer">The writer to write to.</param>
/// <param name="comment">The XmlCodeComment to read comments from.</param>
protected virtual void RenderGenericTypeParameters(List <GenericTypeRef> genericTypes, System.Xml.XmlWriter writer, XmlCodeComment comment)
{
writer.WriteStartElement("genericparameters");
for (int i = 0; i < genericTypes.Count; i++)
{
writer.WriteStartElement("parameter");
writer.WriteElementString("name", genericTypes[i].Name);
writer.WriteStartElement("description");
// find and output the summary
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement paramEntry = comment.Elements.Find(currentBlock =>
currentBlock is TypeParamXmlCodeElement &&
((TypeParamXmlCodeElement)currentBlock).Name == genericTypes[i].Name);
if (paramEntry != null)
{
writer.WriteString(paramEntry.Text);
}
}
writer.WriteEndElement(); // description
writer.WriteEndElement(); // parameter
}
writer.WriteEndElement();
}
/// <summary>
/// Renders a seealso xml block when the specified member has seealso references in the comments.
/// </summary>
/// <param name="member">The member to render the block for.</param>
/// <param name="writer">The writer to write the xml to.</param>
/// <param name="comment">The associated xml comments.</param>
protected void RenderSeeAlsoBlock(ReflectedMember member, System.Xml.XmlWriter writer, XmlCodeComment comment)
{
if (comment != XmlCodeComment.Empty)
{
List <XmlCodeElement> elements = comment.Elements.FindAll(e => e.Element == XmlCodeElements.SeeAlso);
if (elements != null && elements.Count > 0)
{
writer.WriteStartElement("seealsolist");
foreach (SeeAlsoXmlCodeElement current in elements)
{
string displayName = current.Member.TypeName;
Entry entry = this.Document.Find(current.Member);
writer.WriteStartElement("seealso");
if (entry != null)
{
displayName = entry.Name;
ReflectedMember foundMember = entry.Item as ReflectedMember;
if (foundMember != null)
{
writer.WriteAttributeString("id", foundMember.GetGloballyUniqueId().ToString());
this.WriteCref(entry, writer);
}
}
writer.WriteString(displayName);
writer.WriteEndElement(); // seealso
}
writer.WriteEndElement(); // seealsolist
}
}
}
/// <summary>
/// Renders the list of defined exceptions for the specified <paramref name="member"/>.
/// </summary>
/// <param name="member">The member to render the exceptions for.</param>
/// <param name="writer">The writer to write the exceptions to.</param>
/// <param name="comment">The XmlCodeComment to read the exceptions from.</param>
protected virtual void RenderExceptionBlock(ReflectedMember member, System.Xml.XmlWriter writer, XmlCodeComment comment)
{
// output documentation for expected exceptions if they are defined
if (comment != XmlCodeComment.Empty)
{
List <XmlCodeElement> exceptions = comment.Elements.FindAll(node => node is ExceptionXmlCodeElement);
if (exceptions != null && exceptions.Count > 0)
{
writer.WriteStartElement("exceptions");
for (int i = 0; i < exceptions.Count; i++)
{
ExceptionXmlCodeElement current = (ExceptionXmlCodeElement)exceptions[i];
string exceptionName = string.Empty;
ReflectedMember found = null;
if (current.Member.PathType != CRefTypes.Error)
{
TypeDef def = member.Assembly.FindType(current.Member.Namespace, current.Member.TypeName);
exceptionName = string.Format("{0}.{1}", current.Member.Namespace, current.Member.TypeName);
if (def != null)
{
found = def;
switch (current.Member.PathType)
{
// these elements are named and the type of element will
// not modify how it should be displayed
case CRefTypes.Field:
case CRefTypes.Property:
case CRefTypes.Event:
case CRefTypes.Namespace:
break;
// these could be generic and so will need to modify to
// a more appropriate display name
case CRefTypes.Method:
MethodDef method = current.Member.FindIn(def) as MethodDef;
if (method != null)
{
found = method;
exceptionName = method.GetDisplayName(false);
}
break;
case CRefTypes.Type:
exceptionName = def.GetDisplayName(false);
break;
}
}
}
writer.WriteStartElement("exception");
writer.WriteStartElement("name");
if (found != null)
{
writer.WriteAttributeString("key", found.GetGloballyUniqueId().ToString());
writer.WriteAttributeString("cref", current.Member.ToString());
}
writer.WriteString(exceptionName);
writer.WriteEndElement();
writer.WriteStartElement("condition");
for (int j = 0; j < current.Elements.Count; j++)
{
this.Serialize(current.Elements[j], writer);
}
writer.WriteEndElement();
writer.WriteEndElement();
}
writer.WriteEndElement();
}
}
}
/// <summary>
/// Loads and parses the XML Code comments for the <paramref name="crefPathToMember"/> specified
/// element.
/// </summary>
/// <param name="assembly">The assembly the member is defined in.</param>
/// <param name="file">The file containing the xml code comments</param>
/// <param name="crefPathToMember">The conical name path to the member to get documentation for.</param>
/// <returns>A List of blocks for the members commentary.</returns>
public static List <Block> Parse(AssemblyDef assembly, ICommentSource file, CRefPath crefPathToMember)
{
XmlCodeComment comment = file.GetComment(crefPathToMember);
return(Parser.Parse(assembly, comment));
}
public override void Render(System.Xml.XmlWriter writer)
{
CRefPath crefPath = new CRefPath(_member);
XmlCodeComment comment = _xmlComments.GetComment(crefPath);
writer.WriteStartElement("member");
writer.WriteAttributeString("id", this.AssociatedEntry.Key.ToString());
writer.WriteAttributeString("subId", this.AssociatedEntry.SubKey);
writer.WriteAttributeString("type", ReflectionHelper.GetType(_member));
WriteCref(AssociatedEntry, writer);
writer.WriteStartElement("assembly");
writer.WriteAttributeString("file", System.IO.Path.GetFileName(_member.Assembly.FileName));
writer.WriteString(_member.Assembly.Name);
writer.WriteEndElement();
string displayName = _member.GetDisplayName(false);
writer.WriteStartElement("name");
writer.WriteAttributeString("safename", Exporter.CreateSafeName(displayName));
writer.WriteString(displayName);
writer.WriteEndElement();
writer.WriteStartElement("namespace");
Entry namespaceEntry = this.AssociatedEntry.FindNamespace(_member.Namespace);
writer.WriteAttributeString("id", namespaceEntry.Key.ToString());
writer.WriteAttributeString("name", namespaceEntry.SubKey);
writer.WriteAttributeString("cref", $"N:{_member.Namespace}");
writer.WriteString(_member.Namespace);
writer.WriteEndElement();
if (_member.IsGeneric)
{
RenderGenericTypeParameters(_member.GetGenericTypes(), writer, comment);
}
// find and output the summary
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement summary = comment.Elements.Find(currentBlock => currentBlock is SummaryXmlCodeElement);
if (summary != null)
{
this.Serialize(summary, writer);
}
}
RenderSyntaxBlocks(_member, writer);
RenderPermissionBlock(_member, writer, comment);
// find and output the remarks
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is RemarksXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
// find and output the examples
if (comment != XmlCodeComment.Empty)
{
XmlCodeElement remarks = comment.Elements.Find(currentBlock => currentBlock is ExampleXmlCodeElement);
if (remarks != null)
{
Serialize(remarks, writer);
}
}
RenderSeeAlsoBlock(_member, writer, comment);
if (_member.IsEnumeration)
{
writer.WriteStartElement("values");
List <FieldDef> fields = _member.Fields;
for (int i = 0; i < fields.Count; i++)
{
if (fields[i].IsSystemGenerated)
{
continue;
}
CRefPath currentPath = CRefPath.Create(fields[i]);
XmlCodeComment currentComment = _xmlComments.GetComment(currentPath);
writer.WriteStartElement("value");
writer.WriteStartElement("name");
writer.WriteString(fields[i].Name);
writer.WriteEndElement();
writer.WriteStartElement("description");
if (currentComment != XmlCodeComment.Empty && currentComment.Elements != null)
{
XmlCodeElement summary = currentComment.Elements.Find(currentBlock => currentBlock is SummaryXmlCodeElement);
if (summary != null)
{
Serialize(summary, writer);
}
}
writer.WriteEndElement();
writer.WriteEndElement();
}
writer.WriteEndElement();
}
else
{
if (_member.HasMembers)
{
OutputMembers(writer);
}
}
if (!_member.IsDelegate && !_member.IsEnumeration && !_member.IsInterface && !_member.IsStructure)
{
AddInheritanceTree(_member, writer);
}
writer.WriteEndElement(); // member
}