/// <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();
}
private static bool ResolveMember(string innerText, CRefPath path, AssemblyDef assembly, out CrefEntryKey key, out string displayName)
{
key = new CrefEntryKey(assembly, path.ToString());
displayName = innerText;
// check if the member has been output by visual studio. If the cref is empty vs did not find it.
// TODO: Return error text?
if (path.PathType == CRefTypes.Error)
{
return(false);
}
TheBoxSoftware.Documentation.Entry relatedEntry = LiveDocumentorFile.Singleton.LiveDocument.Find(path);
if (relatedEntry != null)
{
displayName = relatedEntry.Name;
switch (path.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 = relatedEntry.Item as MethodDef;
if (method != null)
{
displayName = method.GetDisplayName(false);
}
break;
case CRefTypes.Type:
TypeDef def = relatedEntry.Item as TypeDef;
if (def != null)
{
displayName = def.GetDisplayName(false);
}
break;
}
}
return(relatedEntry != null);
}
public override void Render(System.Xml.XmlWriter writer)
{
Entry entry = Document.Find(_element.Member);
string displayName = string.IsNullOrEmpty(_element.Member.ElementName)
? _element.Member.TypeName
: _element.Member.ElementName;
if (_element.Member.PathType != CRefTypes.Error)
{
writer.WriteStartElement("see");
if (entry != null)
{
displayName = entry.Name;
writer.WriteAttributeString("id", entry.Key.ToString());
writer.WriteAttributeString("cref", _element.Member.ToString());
switch (_element.Member.PathType)
{
case CRefTypes.Namespace:
writer.WriteAttributeString("type", "namespace");
writer.WriteAttributeString("name", displayName);
break;
// these could be generic and so will need to modify to
// a more appropriate display name
case CRefTypes.Method:
MethodDef method = entry.Item as MethodDef;
if (method != null)
{
displayName = method.GetDisplayName(false);
}
break;
case CRefTypes.Type:
TypeDef def = entry.Item as TypeDef;
if (def != null)
{
displayName = def.GetDisplayName(false);
}
break;
}
}
writer.WriteString(displayName);
writer.WriteEndElement(); // element
}
}
private void OutputMembers(System.Xml.XmlWriter writer)
{
if (this.AssociatedEntry.Children.Count == 0)
{
return;
}
writer.WriteStartElement("entries");
List <Entry> children = AssociatedEntry.Children;
Entry constructors = children.Find(entry => entry.Name == "Constructors");
if (constructors != null)
{
var s = from child in constructors.Children orderby child.Name select child;
foreach (Entry current in s)
{
MethodDef currentMember = (MethodDef)current.Item;
WriteEntry(writer, currentMember, currentMember.GetDisplayName(false, true));
}
}
Entry fields = children.Find(entry => entry.Name == "Fields");
if (fields != null)
{
var s = from child in fields.Children orderby child.Name select child;
foreach (Entry current in s)
{
FieldDef currentMember = (FieldDef)current.Item;
WriteEntry(writer, currentMember, currentMember.Name);
}
}
Entry properties = children.Find(entry => entry.Name == "Properties");
if (properties != null)
{
var s = from child in properties.Children orderby child.Name select child;
foreach (Entry current in s)
{
PropertyDef currentMember = current.Item as PropertyDef;
WriteEntry(writer, currentMember, new DisplayNameSignitureConvertor(currentMember, false, true).Convert());
}
}
Entry events = children.Find(entry => entry.Name == "Events");
if (events != null)
{
var s = from child in events.Children orderby child.Name select child;
foreach (Entry current in s)
{
EventDef currentMember = (EventDef)current.Item;
WriteEntry(writer, currentMember, currentMember.Name);
}
}
Entry methods = children.Find(entry => entry.Name == "Methods");
if (methods != null)
{
var s = from child in methods.Children orderby child.Name select child;
foreach (Entry current in s)
{
MethodDef currentMember = (MethodDef)current.Item;
WriteEntry(writer, currentMember, currentMember.GetDisplayName(false, true));
}
}
Entry operators = children.Find(entry => entry.Name == "Operators");
if (operators != null)
{
var s = from child in operators.Children orderby child.Name select child;
foreach (Entry current in s)
{
MethodDef currentMember = (MethodDef)current.Item;
WriteEntry(writer, currentMember, currentMember.GetDisplayName(false));
}
}
// I dont think we have any extension methods anymore - perhaps we can just delete this code?
var extensionMethods = from method in this._member.ExtensionMethods orderby method.Name select method;
foreach (MethodDef currentMethod in extensionMethods)
{
DisplayNameSignitureConvertor displayNameSig = new DisplayNameSignitureConvertor(currentMethod, false, true, true);
WriteEntry(writer, currentMethod, currentMethod.GetDisplayName(false, true), "extensionmethod");
}
writer.WriteEndElement();
}
/// <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>
/// Generates the page contents
/// </summary>
public override void Generate()
{
if (!IsGenerated)
{
CRefPath crefPath = new CRefPath(_method);
List <Block> parsedBlocks = Elements.Parser.Parse(_method.Assembly, _commentsXml, crefPath);
if (!_commentsXml.Exists())
{
Blocks.Add(new NoXmlComments(_method));
}
Blocks.Add(new Elements.Header1(_method.GetDisplayName(false)));
// Add the summary if it exists
if (parsedBlocks != null)
{
Block summary = parsedBlocks.Find(currentBlock => currentBlock is Summary);
if (summary != null)
{
Blocks.Add(summary);
}
}
AddSyntaxBlock(_method);
// Add the type parameters if they exist
if (parsedBlocks != null)
{
List <Block> typeParams = parsedBlocks.FindAll(currentBlock => currentBlock is TypeParamEntry);
if (typeParams.Count > 0)
{
TypeParamSection typeParamSection = new TypeParamSection();
foreach (GenericTypeRef genericType in _method.GenericTypes)
{
string name = genericType.Name;
string description = string.Empty;
foreach (TypeParamEntry current in typeParams)
{
if (current.Param == genericType.Name)
{
description = current.Description;
}
}
typeParamSection.AddEntry(new TypeParamEntry(name, description));
}
Blocks.Add(typeParamSection);
}
}
AddParametersForMethod(_method, parsedBlocks);
AddReturnDetails(parsedBlocks);
// Add the exception table if it exists
if (parsedBlocks != null)
{
Block exceptions = parsedBlocks.Find(currentBlock => currentBlock is ExceptionList);
if (exceptions != null)
{
Blocks.Add(exceptions);
}
}
if (parsedBlocks != null)
{
Block permissions = parsedBlocks.Find(current => current is PermissionList);
if (permissions != null)
{
Blocks.Add(permissions);
}
}
// Add the remarks if it exists
if (parsedBlocks != null)
{
Block remarks = parsedBlocks.Find(currentBlock => currentBlock is Remarks);
if (remarks != null)
{
Blocks.Add(remarks);
}
}
// Add the example if it exists
if (parsedBlocks != null)
{
Block summary = parsedBlocks.Find(currentBlock => currentBlock is Example);
if (summary != null)
{
Blocks.Add(new Header2("Examples"));
Blocks.Add(summary);
}
}
// Add the seealso list if it exists
AddSeeAlso(parsedBlocks);
IsGenerated = true;
}
}