/// <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; }