예제 #1
0
        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();
        }
예제 #2
0
        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();
        }
예제 #3
0
        /// <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();
        }
예제 #4
0
        public void WhenPassedNull_GetComment_ReturnsEmpty()
        {
            XmlCommentFile commentFile = CreateXmlCommentFile("myfile.xml");

            SetFileExistsAndLoadXml(commentFile);

            XmlCodeComment result = commentFile.GetComment(null);

            Assert.AreSame(XmlCodeComment.Empty, result);
        }
예제 #5
0
        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);
        }
예제 #6
0
        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);
        }
예제 #7
0
        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);
        }
예제 #8
0
        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);
        }
예제 #9
0
        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("}");
 }
예제 #11
0
        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);
        }
예제 #12
0
        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);
        }
예제 #13
0
        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());
        }
예제 #15
0
        /// <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();
        }
예제 #17
0
        /// <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();
        }
예제 #22
0
 /// <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();
 }
예제 #23
0
        /// <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
                }
            }
        }
예제 #24
0
        /// <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();
                }
            }
        }
예제 #25
0
        /// <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));
        }
예제 #26
0
        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
        }