/// <summary>
/// Serializes an <see cref="XmlCodeElement"/> to XML.
/// </summary>
/// <param name="comment">The XML code comment to serialize.</param>
/// <param name="writer">The XmlWriter to serialize to.</param>
protected void Serialize(XmlCodeElement comment, System.Xml.XmlWriter writer)
{
if (comment != XmlCodeComment.Empty)
{
if (XmlElementRenderer.IsHandled(comment))
{
XmlRenderer renderer = XmlElementRenderer.Create(this, this.AssociatedEntry, comment);
renderer.Render(writer);
}
else
{
if (comment is XmlContainerCodeElement)
{
writer.WriteStartElement(comment.Element.ToString().ToLower());
foreach (XmlCodeElement element in ((XmlContainerCodeElement)comment).Elements)
{
this.Serialize(element, writer);
}
writer.WriteEndElement();
}
else
{
writer.WriteStartElement(comment.Element.ToString().ToLower());
writer.WriteString(comment.Text);
writer.WriteEndElement();
}
}
}
}
private void RenderXmlBlock(System.Xml.XmlWriter writer, XmlCodeElement element)
{
if (element != null)
{
Serialize(element, writer);
}
}
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>
///
/// </summary>
/// <param name="assembly"></param>
/// <param name="element"></param>
/// <param name="text"></param>
private static void ConvertElement(AssemblyDef assembly, XmlCodeElement element, StringBuilder text)
{
switch (element.Element)
{
case XmlCodeElements.Text:
text.Append(element.Text);
break;
default:
break;
}
}
/// <summary>
/// Checks if the <paramref name="element"/> is handled by an XmlElementRenderer.
/// </summary>
/// <param name="element">The element to check.</param>
/// <returns>True if it can be handled else false.</returns>
public static bool IsHandled(XmlCodeElement element)
{
bool isHandled = false;
switch (element.Element)
{
case XmlCodeElements.See:
case XmlCodeElements.List:
isHandled = true;
break;
}
return(isHandled);
}
private void WriteAsText(StringBuilder builder, XmlCodeElement element)
{
builder.Append("{");
builder.Append(element.Element.ToString());
builder.Append(":");
builder.Append(element.Text);
if (element is XmlContainerCodeElement)
{
foreach (XmlCodeElement child in ((XmlContainerCodeElement)element).Elements)
{
this.WriteAsText(builder, child);
}
}
builder.Append("}");
}
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>
/// Factory method for instantiating correct XmlElementRenderers for the specified
/// <paramref name="element"/>.
/// </summary>
/// <param name="associatedEntry">The entry this comment element was taken from.</param>
/// <param name="element">The XML code comment element to handle.</param>
/// <returns>A valid XmlRenderer for the <paramref name="element"/>.</returns>
public static XmlRenderer Create(XmlRenderer from, Entry associatedEntry, XmlCodeElement element)
{
XmlElementRenderer renderer = null;
switch (element.Element)
{
case XmlCodeElements.See:
renderer = new SeeXmlElementRenderer(associatedEntry, (SeeXmlCodeElement)element);
break;
case XmlCodeElements.List:
renderer = new ListXmlElementRenderer(associatedEntry, (ListXmlCodeElement)element);
break;
}
renderer.Document = from.Document; // need to pass the reference over
return(renderer);
}
/// <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();
}
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
}
private static Inline ParseInline(AssemblyDef assembly, XmlCodeElement element, ParsingSession session)
{
TraceHelper.WriteLine("parsing-inline: e({0})", element.Element.ToString());
switch (element.Element)
{
// Invalid elements
case XmlCodeElements.Code:
case XmlCodeElements.Example:
case XmlCodeElements.Exception:
case XmlCodeElements.List:
case XmlCodeElements.ListHeader:
case XmlCodeElements.ListItem:
case XmlCodeElements.Include:
case XmlCodeElements.Para:
case XmlCodeElements.Param:
case XmlCodeElements.Permission:
case XmlCodeElements.Remarks:
case XmlCodeElements.Returns:
case XmlCodeElements.Summary:
case XmlCodeElements.TypeParam:
case XmlCodeElements.Value:
InvalidOperationException ex = new InvalidOperationException(
"Found a block level element where an inline element was expected."
);
ex.Data["element"] = element;
throw ex;
case XmlCodeElements.B:
return(new Bold(new Run(element.Text)));
case XmlCodeElements.C:
return(new C(element.Text));
case XmlCodeElements.I:
return(new Italic(new Run(element.Text)));
case XmlCodeElements.ParamRef:
return(new Italic(new Run(element.Text)));
case XmlCodeElements.See:
SeeXmlCodeElement seeElement = element as SeeXmlCodeElement;
string displayName;
CrefEntryKey key;
if (Parser.ResolveMember(seeElement.Text, seeElement.Member, assembly, out key, out displayName))
{
return(new See(key, displayName));
}
else
{
return(new Run(displayName));
}
case XmlCodeElements.SeeAlso:
SeeAlsoXmlCodeElement seeAlsoElement = element as SeeAlsoXmlCodeElement;
// key and displayname defined in see
if (Parser.ResolveMember(seeAlsoElement.Text, seeAlsoElement.Member, assembly, out key, out displayName))
{
return(new SeeAlso(key, displayName));
}
else
{
return(new SeeAlso(displayName));
}
case XmlCodeElements.Text:
return(new Run(element.Text));
case XmlCodeElements.TypeParamRef:
return(new Italic(new Run(element.Text)));
}
throw new Exception("Unknown inline parsing error.");
}
private static Block ParseBlock(AssemblyDef assembly, XmlCodeElement element, ParsingSession session)
{
TraceHelper.WriteLine("parsing-block: e({0})", element.Element.ToString());
CrefEntryKey crefEntryKey;
Inline link;
string displayName;
switch (element.Element)
{
// Invalid inline elements
case XmlCodeElements.C:
case XmlCodeElements.ParamRef:
case XmlCodeElements.See:
case XmlCodeElements.SeeAlso:
case XmlCodeElements.Text:
case XmlCodeElements.TypeParamRef:
InvalidOperationException ex = new InvalidOperationException(
"Found an inline element where a block level element was expected."
);
ex.Data["element"] = element;
throw ex;
case XmlCodeElements.Include:
InvalidOperationException includeEx = new InvalidOperationException(
"Found an include comment element, the c# parser has failed."
);
includeEx.Data["element"] = element;
throw includeEx;
// End points
case XmlCodeElements.Code:
return(new Code(element.Text));
case XmlCodeElements.Exception:
ExceptionXmlCodeElement exceptionElement = element as ExceptionXmlCodeElement;
if (Parser.ResolveMember(exceptionElement.Text, exceptionElement.Member, assembly, out crefEntryKey, out displayName))
{
link = link = Parser.CreateHyperlink(crefEntryKey, exceptionElement.Member.TypeName);
}
else
{
if (string.IsNullOrEmpty(displayName))
{
link = new Run(exceptionElement.Member.TypeName);
}
else
{
link = new Run(displayName);
}
}
return(new ExceptionEntry(link, Parser.Parse(assembly, element as ExceptionXmlCodeElement)));
case XmlCodeElements.Example:
ExampleXmlCodeElement exampleElement = element as ExampleXmlCodeElement;
return(new Example(Parser.Parse(assembly, exampleElement)));
case XmlCodeElements.Para:
ParaXmlCodeElement paraElement = element as ParaXmlCodeElement;
return(new Para(Parser.Parse(assembly, paraElement)));
case XmlCodeElements.Permission:
PermissionXmlCodeElement permissionElement = element as PermissionXmlCodeElement;
if (Parser.ResolveMember(permissionElement.Text, permissionElement.Member, assembly, out crefEntryKey, out displayName))
{
link = link = Parser.CreateHyperlink(crefEntryKey, permissionElement.Member.TypeName);
}
else
{
if (string.IsNullOrEmpty(displayName))
{
link = new Run(permissionElement.Member.TypeName);
}
else
{
link = new Run(displayName);
}
}
return(new PermissionEntry(link, Parser.Parse(assembly, element as PermissionXmlCodeElement)));
case XmlCodeElements.Remarks:
return(new Remarks(Parser.Parse(assembly, element as RemarksXmlCodeElement)));
case XmlCodeElements.Returns:
return(new Returns(Parser.Parse(assembly, element as ReturnsXmlCodeElement)));
case XmlCodeElements.Summary:
return(new Summary(Parser.Parse(assembly, element as SummaryXmlCodeElement)));
case XmlCodeElements.Value:
return(new Value(Parser.Parse(assembly, element as ValueXmlCodeElement)));
case XmlCodeElements.Param:
return(new Param(((ParamXmlCodeElement)element).Name, Parser.Parse(assembly, element as ParamXmlCodeElement)));
case XmlCodeElements.TypeParam:
TypeParamXmlCodeElement typeParamElement = (TypeParamXmlCodeElement)element;
return(new TypeParamEntry(typeParamElement.Name, typeParamElement.Text));
case XmlCodeElements.List:
ListXmlCodeElement listElement = (ListXmlCodeElement)element;
return(Parser.ParseList(assembly, listElement));
case XmlCodeElements.Term:
case XmlCodeElements.Description:
Section termOrDescription = new Section();
termOrDescription.Blocks.AddRange(Parser.Parse(assembly, (XmlContainerCodeElement)element));
return(termOrDescription);
break;
}
throw new Exception("WTF, block parsing error");
}
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();
}
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();
}
