/// <include file='code-documentation\entry.xml' path='docs/entry/member[@name="ctor1"]/*' />
public Entry(object item, string displayName, ICommentSource xmlComments)
{
_item = item;
_xmlComments = xmlComments;
_name = displayName;
_children = new List <Entry>();
}
public static Page Create(Entry entry, string type, ICommentSource xmlComments)
{
object forItem = entry.Item;
Page created = null;
switch (type)
{
case "Members":
created = new TypeMembersPage(forItem as TypeDef, xmlComments);
break;
case "Constructors":
created = new TypeConstructorsPage(forItem as List <MethodDef>, xmlComments);
break;
case "Operators":
created = new TypeOperatorsPage(forItem as List <MethodDef>, xmlComments);
break;
case "Component Diagram":
created = new DeploymentDiagram();
break;
}
return(created);
}
/// <summary>
/// Extracts as much information from the state of the exception as possible and returns
/// it as a formatted string.
/// </summary>
/// <returns>The formatted exception details.</returns>
public string GetExtendedInformation()
{
StringBuilder builder = new StringBuilder();
if (this.Comment != null)
{
if (this.Comment == XmlCodeComment.Empty)
{
builder.AppendLine("The associated XmlCodeComment is equal to Empty");
}
else
{
if (this.Comment.Member != null)
{
// get the cref path of the member
try
{
builder.AppendLine($"CRef: {this.Comment.Member.ToString()}");
}
catch (Exception) { }
// if its not null lets just see if we can the base xml for this
try
{
LiveDocumentorFile sf = LiveDocumentorFile.Singleton;
if (sf != null && sf.LiveDocument != null)
{
Documentation.Entry entry = sf.LiveDocument.Find(this.Comment.Member);
if (entry != null && entry.XmlCommentFile != null)
{
ICommentSource commentSource = entry.XmlCommentFile;
builder.AppendLine(
$"Has XML Comments: {commentSource.Exists()}"
);
builder.AppendLine(
$"XML: {commentSource.GetXml(this.Comment.Member)}"
);
}
}
}
catch (Exception) { }
}
builder.AppendLine("Formatted Comment");
this.WriteAsText(builder, this.Comment);
builder.AppendLine();
}
}
else
{
builder.AppendLine("No XmlCodeComment was stored in the exception");
}
return(builder.ToString());
}
/// <summary>
/// Initializes a new instance of the <see cref="NamespaceXmlRenderer"/> class.
/// </summary>
/// <param name="entry">The associated entry.</param>
/// <exception cref="InvalidOperationException">Thrown when an Entry with an invalid Item is provided.</exception>
public AssemblyXmlRenderer(Entry entry)
{
_member = entry.Item as AssemblyDef;
_xmlComments = entry.XmlCommentFile;
AssociatedEntry = entry;
if (_member == null)
{
throw new InvalidOperationException(
$"Entry in DocumentMap is being exported as AssemblyDef when type is '{entry.Item.GetType()}'"
);
}
}
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);
}
/// <summary>
/// Generates the document map for all of the types child elements, fields, properties
/// and methods.
/// </summary>
/// <param name="typeDef">The type to generate the map for.</param>
/// <param name="typeEntry">The entry to add the child elements to.</param>
/// <param name="commentsXml">The assembly comment file.</param>
protected virtual void GenerateTypeMap(TypeDef typeDef, Entry typeEntry, ICommentSource commentsXml)
{
const string CONSTRUCTOR = "Constructors";
const string METHOD = "Methods";
const string OPERATOR = "Operators";
const string FIELD = "Fields";
const string PROPERTY = "Properties";
const string EVENT = "Events";
BuildMethodEntries(CONSTRUCTOR, typeDef.GetConstructors(), typeEntry, commentsXml);
BuildMethodEntries(METHOD, typeDef.GetMethods(), typeEntry, commentsXml);
BuildMethodEntries(OPERATOR, typeDef.GetOperators(), typeEntry, commentsXml);
BuildEntries <FieldDef>(FIELD, typeDef.GetFields(), typeEntry, commentsXml);
BuildEntries <PropertyDef>(PROPERTY, typeDef.GetProperties(), typeEntry, commentsXml);
BuildEntries <EventDef>(EVENT, typeDef.GetEvents(), typeEntry, commentsXml);
}
/// <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>
/// Adds a table of the <paramref name="types"/> to the document with a header <paramref name="name"/>.
/// </summary>
/// <param name="name">The header text.</param>
/// <param name="types">The types to add to the table.</param>
/// <param name="xmlFile">The XML file to read comments from.</param>
private void OutputTypes(string name, IOrderedEnumerable <TypeDef> types, ICommentSource xmlFile)
{
if (types.Count() != 0)
{
SummaryTable classTable = new SummaryTable();
foreach (TypeDef currentType in types)
{
CRefPath crefPath = new CRefPath(currentType);
// Find the description for the type
Block description = this.GetSummaryFor(
xmlFile,
currentType.Assembly,
crefPath
);
Hyperlink nameLink = new Hyperlink(new Run(currentType.GetDisplayName(false)));
nameLink.Tag = new EntryKey(currentType.GetGloballyUniqueId());
nameLink.Click += new System.Windows.RoutedEventHandler(LinkHelper.Resolve);
classTable.AddItem(nameLink, description, Model.ElementIconConstants.GetIconPathFor(currentType));
}
this.Blocks.Add(new Header2(name));
this.Blocks.Add(classTable);
}
}
/// <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));
}
protected override Entry GenerateDocumentForAssembly(DocumentMap map, DocumentedAssembly current, ref int fileCounter)
{
AssemblyDef assembly = AssemblyDef.Create(current.FileName);
current.LoadedAssembly = assembly;
XmlCommentFile commentFile = new XmlCommentFile(current.XmlFileName, new FileSystem());
commentFile.Load();
ICommentSource xmlComments = commentFile; // not nice having to call load then cast we wil have to fix this
Entry assemblyEntry = this.EntryCreator.Create(assembly, System.IO.Path.GetFileName(current.FileName), xmlComments);
current.UniqueId = assembly.UniqueId = fileCounter++;
assemblyEntry.Key = assembly.GetGloballyUniqueId();
assemblyEntry.IsSearchable = false;
// Add the namespaces to the document map
Dictionary <string, List <TypeDef> > typesInNamespaces = assembly.GetTypesInNamespaces();
foreach (KeyValuePair <string, List <TypeDef> > currentNamespace in typesInNamespaces)
{
if (string.IsNullOrEmpty(currentNamespace.Key) || currentNamespace.Value.Count == 0)
{
continue;
}
string namespaceSubKey = this.BuildSubkey(currentNamespace);
Entry namespaceEntry = this.FindByKey(map, assemblyEntry.Key, namespaceSubKey, false);
if (namespaceEntry == null)
{
namespaceEntry = this.EntryCreator.Create(currentNamespace, currentNamespace.Key, xmlComments, assemblyEntry);
namespaceEntry.Key = assemblyEntry.Key;
namespaceEntry.SubKey = namespaceSubKey;
namespaceEntry.IsSearchable = false;
}
// Add the types from that namespace to its map
foreach (TypeDef currentType in currentNamespace.Value)
{
if (currentType.Name.StartsWith("<"))
{
continue;
}
PreEntryAddedEventArgs e = new PreEntryAddedEventArgs(currentType);
this.OnPreEntryAdded(e);
if (!e.Filter)
{
Entry typeEntry = this.EntryCreator.Create(currentType, currentType.GetDisplayName(false), xmlComments, namespaceEntry);
typeEntry.Key = currentType.GetGloballyUniqueId();
typeEntry.IsSearchable = true;
// For some elements we will not want to load the child objects
// this is currently for System.Enum derived values.
if (
currentType.InheritsFrom != null && currentType.InheritsFrom.GetFullyQualifiedName() == "System.Enum" ||
currentType.IsDelegate)
{
// Ignore children
}
else
{
this.GenerateTypeMap(currentType, typeEntry, xmlComments);
typeEntry.Children.Sort();
}
namespaceEntry.Children.Add(typeEntry);
}
}
if (namespaceEntry.Children.Count > 0)
{
assemblyEntry.Children.Add(namespaceEntry);
namespaceEntry.Children.Sort();
}
}
assemblyEntry.Children.Sort();
return(assemblyEntry);
}
/// <summary>
/// Initializes a new instance of the <see cref="TypeMembersXmlRenderer"/> class.
/// </summary>
/// <param name="entry">The associated entry.</param>
public TypeMembersXmlRenderer(Entry entry)
{
_containingType = (TypeDef)entry.Parent.Item;
_xmlComments = entry.XmlCommentFile;
AssociatedEntry = entry;
}
/// <summary>
/// Initialises a new instance of the EnumerationPage class.
/// </summary>
/// <param name="type">The type to display in the page</param>
/// <param name="xmlComments">The xml comments document for the assembly</param>
public EnumerationPage(TypeDef type, ICommentSource xmlComments)
{
_representedType = type;
_commentsXml = xmlComments;
}
/// <summary>
/// Initialises a new instance of the TypeFieldsPage class
/// </summary>
/// <param name="fields">The fields to manage</param>
/// <param name="xmlComments">The xml comments</param>
public TypeFieldsPage(List <FieldDef> fields, ICommentSource xmlComments)
{
_fields = fields;
_xmlComments = xmlComments;
}
public TypeConstructorsPage(List <MethodDef> typesMethods, ICommentSource xmlComments)
{
this.typesMethods = typesMethods;
this.xmlComments = xmlComments;
}
/// <summary>
/// Initializes a new instance of the <see cref="FieldXmlRenderer"/> class.
/// </summary>
/// <param name="entry">The entry to initialise the renderer with.</param>
public FieldXmlRenderer(Entry entry)
{
_member = (FieldDef)entry.Item;
_xmlComments = entry.XmlCommentFile;
AssociatedEntry = entry;
}
/// <summary>
/// Initializes a new instance of the <see cref="TypeXmlRenderer"/> class.
/// </summary>
/// <param name="entry">The entry in the document map to initialise the renderer with.</param>
public TypeXmlRenderer(Entry entry)
{
_member = (TypeDef)entry.Item;
_xmlComments = entry.XmlCommentFile;
AssociatedEntry = entry;
}
protected override Entry GenerateDocumentForAssembly(DocumentMap map, DocumentedAssembly current, ref int fileCounter)
{
AssemblyDef assembly = GetAssemblyDef(current);
ICommentSource xmlComments = GetXmlCommentFile(current);
Entry assemblyEntry = EntryCreator.Create(assembly, System.IO.Path.GetFileName(current.FileName), xmlComments);
current.UniqueId = assembly.UniqueId = fileCounter++;
assemblyEntry.Key = assembly.GetGloballyUniqueId();
assemblyEntry.IsSearchable = false;
Entry namespaceEntry = null;
// Add the namespaces to the document map
Dictionary <string, List <TypeDef> > typesInNamespaces = assembly.GetTypesInNamespaces();
foreach (KeyValuePair <string, List <TypeDef> > currentNamespace in typesInNamespaces)
{
if (currentNamespace.Value.Count == 0)
{
continue;
}
string namespaceSubKey = BuildSubkey(currentNamespace);
namespaceEntry = Find(map, namespaceSubKey);
if (namespaceEntry == null)
{
string displayName = currentNamespace.Key;
if (string.IsNullOrEmpty(currentNamespace.Key))
{
displayName = "None";
}
namespaceEntry = EntryCreator.Create(currentNamespace, displayName, xmlComments);
namespaceEntry.Key = assemblyEntry.Key;
namespaceEntry.SubKey = namespaceSubKey;
namespaceEntry.IsSearchable = false;
}
// Add the types from that namespace to its map
foreach (TypeDef currentType in currentNamespace.Value)
{
if (currentType.IsCompilerGenerated || currentType.Name[0] == '<')
{
continue;
}
PreEntryAddedEventArgs e = new PreEntryAddedEventArgs(currentType);
this.OnPreEntryAdded(e);
if (!e.Filter)
{
Entry typeEntry = EntryCreator.Create(currentType, currentType.GetDisplayName(false), xmlComments, namespaceEntry);
typeEntry.Key = currentType.GetGloballyUniqueId();
typeEntry.IsSearchable = true;
// For some elements we will not want to load the child objects
// this is currently for System.Enum derived values.
if
(
currentType.InheritsFrom != null && currentType.InheritsFrom.GetFullyQualifiedName() == "System.Enum" ||
currentType.IsDelegate)
{
// Ignore children
}
else
{
this.GenerateTypeMap(currentType, typeEntry, xmlComments);
typeEntry.Children.Sort();
}
namespaceEntry.Children.Add(typeEntry);
}
}
if (namespaceEntry.Children.Count > 0)
{
namespaceEntry.Children.Sort();
// we still need to add here otherwise we get duplicate namespaces.
assemblyEntry.Children.Add(namespaceEntry);
if (!map.Contains(namespaceEntry))
{
map.Add(namespaceEntry);
}
else
{
// update the type list is the contianing namespace
KeyValuePair <string, List <TypeDef> > original = (KeyValuePair <string, List <TypeDef> >)namespaceEntry.Item;
original.Value.AddRange(currentNamespace.Value);
}
}
}
// we are not interested in assemblies being used here so make them childless
return(this.EntryCreator.Create(null, string.Empty, null));
}
/// <summary>
/// Initialises a new instance of the NamespacePage class
/// </summary>
/// <param name="item">The namespace details as a list of methods</param>
/// <param name="commentsXml">The code comments file to get comments from</param>
public NamespacePage(KeyValuePair <string, List <TypeDef> > item, ICommentSource commentsXml)
{
_item = item;
_commentsXml = commentsXml;
}
/// <include file='code-documentation\entry.xml' path='docs/entry/member[@name="ctor2"]/*' />
public Entry(object item, string displayName, ICommentSource xmlComments, Entry parent)
: this(item, displayName, xmlComments)
{
_parent = parent;
}
/// <summary>
/// Initialises a new MethodPage class
/// </summary>
/// <param name="method">The method this page is to document</param>
/// <param name="commentsXml">The comments document</param>
public MethodPage(MethodDef method, ICommentSource commentsXml)
: base()
{
_method = method;
_commentsXml = commentsXml;
}
/// <summary>
/// Initializes a new instance of the <see cref="MethodXmlRenderer"/> class.
/// </summary>
/// <param name="entry">The entry to initialise the renderer with.</param>
public MethodXmlRenderer(Entry entry)
{
_member = entry.Item as MethodDef;
_xmlComments = entry.XmlCommentFile;
AssociatedEntry = entry;
}
/// <summary>
/// Initialises a new TypePage instance
/// </summary>
/// <param name="type">The type this page is to document</param>
/// <param name="commentsXml">The code comments file to read the comments from</param>
public TypePage(TypeDef type, ICommentSource commentsXml)
{
_representedType = type;
_commentsXml = commentsXml;
}
/// <summary>
/// Initialises a new instance of the TypeEventsPage class.
/// </summary>
/// <param name="typesEvents">The events defined in the type.</param>
/// <param name="xmlComments">The associated defining libraries xml code comments file.</param>
public TypeEventsPage(List <EventDef> typesEvents, ICommentSource xmlComments)
{
this.typesEvents = typesEvents;
this.xmlComments = xmlComments;
}
public TypeMethodsPage(List <MethodDef> typesMethods, ICommentSource xmlComments)
{
_typesMethods = typesMethods;
_xmlComments = xmlComments;
}
/// <summary>
/// Initialises a new instance of the AssemblyPage class.
/// </summary>
/// <param name="assembly">The assembly to document.</param>
/// <param name="xmlComments">The xml code comments file associated with the assembly.</param>
public AssemblyPage(AssemblyDef assembly, ICommentSource xmlComments) : base()
{
this.InitializeComponent();
this.assembly = assembly;
}
public override void Generate()
{
if (!IsGenerated)
{
TypeDef definingType = null;
if (_typesMethods != null && _typesMethods.Count > 0)
{
definingType = _typesMethods[0].Type as TypeDef;
}
if (!_xmlComments.Exists())
{
Blocks.Add(new NoXmlComments(definingType));
}
Blocks.Add(new Header1(definingType.GetDisplayName(false) + " Methods"));
if (_typesMethods != null && _typesMethods.Count > 0)
{
SummaryTable methods = new SummaryTable();
var sortedMethods = from method in this._typesMethods
where !method.IsConstructor
orderby method.Name
where !LiveDocumentorFile.Singleton.LiveDocument.IsMemberFiltered(method)
select method;
foreach (MethodDef currentMethod in sortedMethods)
{
System.Windows.Documents.Hyperlink link = new System.Windows.Documents.Hyperlink();
link.Inlines.Add(new System.Windows.Documents.Run(currentMethod.GetDisplayName(false)));
link.Tag = new EntryKey(currentMethod.GetGloballyUniqueId());
link.Click += new System.Windows.RoutedEventHandler(LinkHelper.Resolve);
CRefPath path = new CRefPath(currentMethod);
System.Windows.Documents.Block description = this.GetSummaryFor(_xmlComments,
currentMethod.Assembly,
path
);
methods.AddItem(link, description, Model.ElementIconConstants.GetIconPathFor(currentMethod));
}
Blocks.Add(methods);
}
if (definingType != null && definingType.ExtensionMethods.Count > 0)
{
SummaryTable methods = new SummaryTable();
var sortedMethods = from method in definingType.ExtensionMethods
where !method.IsConstructor
orderby method.Name
where !LiveDocumentorFile.Singleton.LiveDocument.IsMemberFiltered(method)
select method;
foreach (MethodDef currentMethod in sortedMethods)
{
DisplayNameSignitureConvertor displayNameSig = new DisplayNameSignitureConvertor(currentMethod, false, true, true);
System.Windows.Documents.Hyperlink link = new System.Windows.Documents.Hyperlink();
link.Inlines.Add(new System.Windows.Documents.Run(displayNameSig.Convert()));
link.Tag = new EntryKey(currentMethod.GetGloballyUniqueId());
link.Click += new System.Windows.RoutedEventHandler(LinkHelper.Resolve);
CRefPath path = new CRefPath(currentMethod);
System.Windows.Documents.Block description = this.GetSummaryFor(_xmlComments,
currentMethod.Assembly,
path
);
methods.AddItem(link, description, Model.ElementIconConstants.GetIconPathFor(currentMethod));
}
Blocks.Add(new Header2("Extension Methods"));
Blocks.Add(methods);
}
IsGenerated = true;
// we also no longer need to store a reference to the XML file I think so we can remove it
_xmlComments = null;
_typesMethods = null;
}
}
public CommentService(ICommentSource commentRepository, ICacheService <PostId, IEnumerable <Comment> > commentServiceCache)
{
this.commentRepository = commentRepository;
this.commentServiceCache = commentServiceCache;
}
/// <summary>
/// Initialises a new instance of the EventPage class.
/// </summary>
/// <param name="eventDef">The event to be documented.</param>
/// <param name="xmlComments">The xml comments associated with the defining library.</param>
public EventPage(EventDef eventDef, ICommentSource xmlComments)
{
this.eventDef = eventDef;
this.xmlComments = xmlComments;
}
/// <summary>
/// Initialises a new FieldPage class.
/// </summary>
/// <param name="field">The field this page rerpresents.</param>
/// <param name="xmlComments">The xml comments file for the library.</param>
public FieldPage(FieldDef field, ICommentSource xmlComments)
{
this._field = field;
this._xmlComments = xmlComments;
}
/// <summary>
/// Initialises a new instance of the TypePropertiesPage class.
/// </summary>
/// <param name="properties">The properties to display.</param>
/// <param name="xmlComments">The assemblies xml comments file</param>
public TypePropertiesPage(List <PropertyDef> properties, ICommentSource xmlComments)
{
_properties = properties;
_xmlComments = xmlComments;
}
