/*       Copyright (c) Eric Ledoux.  All rights reserved.       */
/* See http://www.dwell.net/terms for code sharing information. */

// Topic.cs
//
// Implements class Topic and related types.
//

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Diagnostics;
using System.IO;
using System.Text;
using System.Text.RegularExpressions;
using System.Web.UI;
using System.Xml;
using DwellNet.CodeDoc;
using CodeDocApi.Properties;

namespace DwellNet.CodeDoc
{

[DebuggerDisplay("{DebuggerDisplay}")]
public class Topic : IComparable<Topic>
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    static readonly Regex s_nonFileNameCharRegex =
        new Regex(@"[^a-zA-Z0-9_~\[\],.]");

    static readonly Regex s_insignificantWhiteSpaceRegex =
        new Regex(@"[ \r\n\t]+");

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    DocumentationSet m_docSet;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_name;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    int m_id;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TopicKind m_topicKind;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_parentTopic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    SourceFile m_sourceFile;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    XmlCommentToken m_xmlCommentToken;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_xml;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Token m_startOfDeclaration;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_modifiers;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_namespaceName;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    NamespaceTopic m_namespaceTopic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_memberType;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_explicitPrefix;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_memberName;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList[] m_typeParameters;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList[] m_baseTypes;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_baseClassTopic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_constraints;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<Parameter> m_parameters;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    MethodKind m_methodKind;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    PropertyKind m_propertyKind;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<string> m_enumValueNames;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<TokenList> m_attributes;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Accessor m_getAccessor;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Accessor m_setAccessor;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    UsingContext m_usingContext;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<Topic> m_childTopics;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    bool m_isTypeTopic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    bool m_isDocumented;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    OverloadListTopic m_overloadListTopic;

    List<XmlCommentSection>[] m_xmlSectionsHtml;

    //////////////////////////////////////////////////////////////////////////
    // Private Properties
    //

#if DEBUG
    /// <summary>
    /// Gets a string displayed in the debugger.
    /// </summary>
    public string DebuggerDisplay
    {
        get
        {
            TokenList nameList = QualifiedMemberName;
            if (nameList == null)
                return TopicKind.ToString();
            string name = nameList.ToString();
            if (name == null)
                return TopicKind.ToString();
            else
            {
                string moreInfo;
                if (TopicKind == TopicKind.MethodTopic)
                {
                    if (MethodKind != MethodKind.Normal)
                        moreInfo = String.Format(" ({0})", MethodKind);
                    else
                        moreInfo = "";
                }
                else
                if (TopicKind == TopicKind.PropertyTopic)
                {
                    if (PropertyKind != PropertyKind.Normal)
                        moreInfo = String.Format(" ({0})", PropertyKind);
                    else
                        moreInfo = "";
                }
                else
                    moreInfo = "";
                return String.Format("{0} {1}{2}", TopicKind,
                    QualifiedMemberName, moreInfo);
            }
        }
    }
#endif

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public DocumentationSet DocumentationSet
    {
        [DebuggerStepThrough]
        get
        {
            return m_docSet;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_docSet = value;
        }
    }

    public TopicKind TopicKind
    {
        [DebuggerStepThrough]
        get
        {
            return m_topicKind;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_topicKind = value;
        }
    }

    public Topic ParentTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_parentTopic;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_parentTopic = value;
        }
    }

    public SourceFile SourceFile
    {
        [DebuggerStepThrough]
        get
        {
            return m_sourceFile;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_sourceFile = value;
        }
    }

    public XmlCommentToken FirstXmlComment
    {
        [DebuggerStepThrough]
        get
        {
            return m_xmlCommentToken;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_xmlCommentToken = value;
                // do nothing if there is no array of 
        }
    }

    public string Xml
    {
        [DebuggerStepThrough]
        get
        {
            return m_xml;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_xml = value;
        }
    }

    public Token StartOfDeclaration
    {
        [DebuggerStepThrough]
        get
        {
            return m_startOfDeclaration;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_startOfDeclaration = value;
                // do nothing if there is no array of 
        }
    }

    public TokenList Modifiers
    {
        [DebuggerStepThrough]
        get
        {
            return m_modifiers;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_modifiers = value;
        }
    }

    public TokenList NamespaceName
    {
        [DebuggerStepThrough]
        get
        {
            return m_namespaceName;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_namespaceName = value;
        }
    }

    public NamespaceTopic NamespaceTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_namespaceTopic;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_namespaceTopic = value;
        }
    }

    public TokenList ParentTypeName
    {
        get
        {
            if ((ParentTopic == null) ||
                (TopicKind == TopicKind.NamespaceTopic))
                return null;
            TokenList tokenList = new TokenList();
            if (ParentTopic.CopyTypeName(tokenList))
                return tokenList;
            else
                return null;
        }
    }

    public TokenList MemberType
    {
        [DebuggerStepThrough]
        get
        {
            return m_memberType;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_memberType = value;
        }
    }

    public TokenList ExplicitPrefix
    {
        [DebuggerStepThrough]
        get
        {
            return m_explicitPrefix;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_explicitPrefix = value;
        }
    }

    public string MemberName
    {
        [DebuggerStepThrough]
        get
        {
            return m_memberName;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_memberName = value;
        }
    }

    public TokenList[] TypeParameters
    {
        [DebuggerStepThrough]
        get
        {
            return m_typeParameters;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_typeParameters = value;
        }
    }

    public TokenList[] BaseTypes
    {
        [DebuggerStepThrough]
        get
        {
            return m_baseTypes;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_baseTypes = value;
        }
    }

    public Topic BaseClassTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_baseClassTopic;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_baseClassTopic = value;
        }
    }

    public TokenList Constraints
    {
        [DebuggerStepThrough]
        get
        {
            return m_constraints;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_constraints = value;
        }
    }

    public IList<Parameter> Parameters
    {
        [DebuggerStepThrough]
        get
        {
            if (m_parameters == null)
                return null;
            else
                return new ReadOnlyCollection<Parameter>(m_parameters);
        }
    }

    public Parameter[] ParametersArray
    {
        get
        {
            if ((m_parameters == null) || (m_parameters.Count == 0))
                return null;
            else
                return m_parameters.ToArray();
        }
    }

    internal List<Parameter> ParametersList
    {
        [DebuggerStepThrough]
        get
        {
            return m_parameters;
        }
        [DebuggerStepThrough]
        set
        {
            m_parameters = value;
        }
    }

    public MethodKind MethodKind
    {
        [DebuggerStepThrough]
        get
        {
            return m_methodKind;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_methodKind = value;
        }
    }

    public PropertyKind PropertyKind
    {
        [DebuggerStepThrough]
        get
        {
            return m_propertyKind;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_propertyKind = value;
        }
    }

    public IList<string> EnumValueNames
    {
        [DebuggerStepThrough]
        get
        {
            if ((m_enumValueNames == null) || (m_enumValueNames.Count == 0))
                return null;
            else
                return new ReadOnlyCollection<string>(m_enumValueNames);
        }
    }

    public string[] EnumValueNamesArray
    {
        get
        {
            if ((m_enumValueNames == null) || (m_enumValueNames.Count == 0))
                return null;
            else
                return m_enumValueNames.ToArray();
        }
    }

    internal List<string> EnumValueNamesList
    {
        [DebuggerStepThrough]
        get
        {
            return m_enumValueNames;
        }
        [DebuggerStepThrough]
        set
        {
            m_enumValueNames = value;
        }
    }

    public IList<TokenList> Attributes
    {
        [DebuggerStepThrough]
        get
        {
            if ((m_attributes == null) || (m_attributes.Count == 0))
                return null;
            else
                return new ReadOnlyCollection<TokenList>(m_attributes);
        }
    }

    public Accessor GetAccessor
    {
        [DebuggerStepThrough]
        get
        {
            return m_getAccessor;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_getAccessor = value;
        }
    }

    public Accessor SetAccessor
    {
        [DebuggerStepThrough]
        get
        {
            return m_setAccessor;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_setAccessor = value;
        }
    }

    public UsingContext UsingContext
    {
        [DebuggerStepThrough]
        get
        {
            return m_usingContext;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_usingContext = value;
        }
    }

    public IList<Topic> ChildTopics
    {
        [DebuggerStepThrough]
        get
        {
            if (m_childTopics == null)
                return new ReadOnlyCollection<Topic>(new List<Topic>());
            else
                return new ReadOnlyCollection<Topic>(m_childTopics);
        }
    }

    public IEnumerable<MemberInfo> MemberTopics
    {
        get
        {
            // first, yield all documented non-overload-list topics that are
            // children of this topic; keep track of the signature of yielded
            // topics in <signatures>
            Dictionary<string, bool> signatures;
            if (TopicKind == TopicKind.ClassTopic)
                signatures = new Dictionary<string, bool>(20);
            else
                signatures = null;
            foreach (Topic memberTopic in ChildTopics)
            {
                if (!memberTopic.IsDocumented ||
                        (memberTopic is OverloadListTopic))
                    continue;
                yield return new MemberInfo(memberTopic, null);
                if (TopicKind == TopicKind.ClassTopic)
                {
                    string signature = memberTopic.GetOverloadingSignature();
                    if (signature != null)
                        signatures[signature] = true;
                }
            }

            // if this topic isn't a class topic, we're done
            if (TopicKind != TopicKind.ClassTopic)
                yield break;

            // loop once for each ancestor class
            Topic baseClassTopic = BaseClassTopic;
            int inherited = 0;
            while (baseClassTopic != null)
            {
                // yield topics that should be added to the list of member
                // topics, i.e. documented non-overload-list property or method
                // topics (excluding constructors and destructors) that are
                // public or protected and which don't have a signature of a
                // topic we've already yielded
                foreach (Topic memberTopic in baseClassTopic.ChildTopics)
                {
                    if (!memberTopic.IsDocumented)
                        continue; // not a documented topic
                    if (memberTopic is OverloadListTopic)
                        continue; // skip overload list topics
                    if (!memberTopic.HasModifier("public", "protected"))
                        continue; // not public or protected
                    string signature = memberTopic.GetOverloadingSignature();
                    if (signature == null)
                        continue; // not an overloadable property or method
                    bool unused;
                    if (signatures.TryGetValue(signature, out unused))
                        continue; // overridden
                    yield return new MemberInfo(memberTopic, baseClassTopic);
                    signatures.Add(signature, true);
                    inherited++;
                }

                // continue up the inheritance tree
                baseClassTopic = baseClassTopic.BaseClassTopic;
            }

            // for debugging purposes: display the number of inherited members
#if false && DEBUG
            if (inherited > 0)
            {
                Console.WriteLine("{0}: inherited {1} members", this,
                    inherited);
            }
#endif
        }
    }

    public IEnumerable<Topic> DescendentTopics
    {
        get
        {
            foreach (Topic childTopic in ChildTopics)
            {
                yield return childTopic;
                foreach (Topic descendentTopic in childTopic.DescendentTopics)
                    yield return descendentTopic;
            }
        }
    }

    public bool IsTypeTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_isTypeTopic;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_isTypeTopic = value;
        }
    }

    public bool IsDocumented
    {
        [DebuggerStepThrough]
        get
        {
            return m_isDocumented;
        }
        [DebuggerStepThrough]
        set
        {
            m_isDocumented = value;
        }
    }

    public bool CanLinkTo
    {
        get
        {
            return IsDocumented ||
                ((TopicKind == TopicKind.EnumValueTopic) &&
                 (ParentTopic != null) &&
                 (ParentTopic.TopicKind == TopicKind.EnumTopic) &&
                 ParentTopic.IsDocumented);
        }
    }

    public OverloadListTopic OverloadListTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_overloadListTopic;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_overloadListTopic = value;
        }
    }

    public TokenList[] AttributesArray
    {
        get
        {
            if ((m_attributes == null) || (m_attributes.Count == 0))
                return null;
            else
                return m_attributes.ToArray();
        }
    }

    internal List<TokenList> AttributesList
    {
        [DebuggerStepThrough]
        get
        {
            return m_attributes;
        }
        [DebuggerStepThrough]
        set
        {
            m_attributes = value;
        }
    }

    public string TopicKindCSharpKeyword
    {
        get
        {
            switch (TopicKind)
            {
            case TopicKind.NamespaceTopic:
                return "namespace";
            case TopicKind.ClassTopic:
                return "class";
            case TopicKind.StructTopic:
                return "struct";
            case TopicKind.InterfaceTopic:
                return "interface";
            case TopicKind.EventTopic:
                return "event";
            case TopicKind.DelegateTopic:
                return "delegate";
            case TopicKind.EnumTopic:
                return "enum";
            case TopicKind.UnknownTopic:
                return "unknown";
            default:
                return TopicKind.ToString();
            }
        }
    }

    public string TopicKindTitle
    {
        get
        {
            switch (TopicKind)
            {
            case TopicKind.NamespaceTopic:
                return Resources.NamespaceTopicTitle;
            case TopicKind.ClassTopic:
                return Resources.ClassTopicTitle;
            case TopicKind.StructTopic:
                return Resources.StructTopicTitle;
            case TopicKind.InterfaceTopic:
                return Resources.InterfaceTopicTitle;
            case TopicKind.EventTopic:
                return Resources.EventTopicTitle;
            case TopicKind.DelegateTopic:
                return Resources.DelegateTopicTitle;
            case TopicKind.EnumTopic:
                return Resources.EnumTopicTitle;
            case TopicKind.EnumValueTopic:
                return Resources.EnumValueTopicTitle;
            case TopicKind.MethodTopic:
                return Resources.MethodTopicTitle;
            case TopicKind.PropertyTopic:
                return Resources.PropertyTopicTitle;
            case TopicKind.FieldTopic:
                return Resources.FieldTopicTitle;
            default:
                return Resources.UnknownTopicTitle;
            }
        }
    }

    public TokenList QualifiedMemberName
    {
        get
        {
            TokenList result = new TokenList();
            ConstructQualifiedMemberName(result, true, true, false);
            if (result.IsEmpty)
                return null;
            else
                return result;
        }
    }

    public TokenList QualifiedMemberNameWithoutNamespace
    {
        get
        {
            TokenList result = new TokenList();
            ConstructQualifiedMemberName(result, false, true, false);
            if (result.IsEmpty)
                return null;
            else
                return result;
        }
    }

    public TokenList CanonicalName
    {
        get
        {
            // set <result> to the canonicalized version of
            // <QualifiedMemberName>
            TokenList result = CanonicalizeMemberName(
                QualifiedMemberName, !IsTypeTopic);

            // if this is a type with type parameters, append their
            // canonicalized representation, e.g. "<,,>"
            if (IsTypeTopic && (m_typeParameters != null))
            {
                result.Append(new Token(SourceFile.LAngle));
                for (int i = 0; i < m_typeParameters.Length - 1; i++)
                    result.Append(new Token(','));
                result.Append(new Token(SourceFile.RAngle));
            }

            return result;
        }
    }

    public string BaseName
    {
        get
        {
            return String.Format("{0}.{1}",
                MakeValidFileName(QualifiedMemberName.ToString()),
                TopicKindTitle.Replace(" ", ""));
        }
    }

    public string Name
    {
        [DebuggerStepThrough]
        get
        {
            return m_name;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_name = value;
        }
    }

    public int Id
    {
        [DebuggerStepThrough]
        get
        {
            return m_id;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_id = value;
        }
    }

    public string DocHtmlFileName
    {
        get
        {
            return Name + ".htm";
        }
    }

    public string CodeHtmlBlockBookmark
    {
        get
        {
            return String.Format("Topic{0}", Id);
        }
    }

    public string CodeHtmlUrl
    {
        get
        {
            if (TopicKind == TopicKind.NamespaceTopic)
                return CodeNamespaceHtmlFileName;
            else
            if (this is OverloadListTopic)
                return CodeOverloadListHtmlFileName;
            else
            if (TopicKind == TopicKind.NamespaceTopic)
                return CodeNamespaceHtmlFileName;
            else
            if (SourceFile == null)
                return null;
            else
            {
                return String.Format("{0}#{1}", SourceFile.CodeHtmlFileName,
                    CodeHtmlBlockBookmark);
            }
        }
    }

    public string CodeNamespaceHtmlFileName
    {
        get
        {
            if (this is NamespaceTopic)
                return String.Format("{0}.CodeNamespace.htm", Name);
            else
                return null;
        }
    }

    public string CodeOverloadListHtmlFileName
    {
        get
        {
            if (this is OverloadListTopic)
                return String.Format("{0}.CodeOverload.htm", Name);
            else
                return null;
        }
    }

    public bool IsGlobalNamespace
    {
        get
        {
            return (TopicKind == TopicKind.NamespaceTopic) &&
                (MemberName.Length == 0);
        }
    }

    public string VeryShortTitleNoKind
    {
        get
        {
            if (IsGlobalNamespace)
                return Resources.GlobalNamespace;
            TokenList name = new TokenList();
            ConstructQualifiedMemberName(name, false, false, true);
            if (name.IsEmpty)
                return TopicKindTitle;
            else
                return GetTitle(name.ToString(), false);
        }
    }

    public string VeryShortTitle
    {
        get
        {
            if (IsGlobalNamespace)
                return Resources.GlobalNamespace;
            TokenList name = new TokenList();
            ConstructQualifiedMemberName(name, false, false, true);
            if (name.IsEmpty)
                return TopicKindTitle;
            else
                return GetTitle(name.ToString(), true);
        }
    }

    public string ShortTitle
    {
        get
        {
            if (IsGlobalNamespace)
                return Resources.GlobalNamespace;
            TokenList name = new TokenList();
            bool includeParentType =
                ((TopicKind != TopicKind.MethodTopic) ||
                 !((MethodKind == MethodKind.Constructor) ||
                   (MethodKind == MethodKind.Destructor)));
            ConstructQualifiedMemberName(name, false, includeParentType, true);
            if (name.IsEmpty)
                return TopicKindTitle;
            else
                return GetTitle(name.ToString(), true);
        }
    }

    public string LongTitle
    {
        get
        {
            if (IsGlobalNamespace)
                return Resources.GlobalNamespace;
            TokenList name = new TokenList();
            ConstructQualifiedMemberName(name, true, true, true);
            if (name.IsEmpty)
                return TopicKindTitle;
            else
                return GetTitle(name.ToString(), true);
        }
    }

    public string ShortSignature
    {
        get
        {
            TokenList name = new TokenList();
            ConstructQualifiedMemberName(name, false, true, true);
            if (name.IsEmpty)
                return TopicKindTitle;
            else
                return GetTitle(name.ToString(), false);
        }
    }

    public string LongSignature
    {
        get
        {
            TokenList name = new TokenList();
            ConstructQualifiedMemberName(name, true, true, true);
            if (name.IsEmpty)
                return TopicKindTitle;
            else
                return GetTitle(name.ToString(), false);
        }
    }

    public string Location
    {
        get
        {
            if (SourceFile != null)
            {
                return String.Format("{0}({1})",
                    SourceFile.SourceFileAbsolutePath,
                    GetDeclarationLineNumber());
            }
            else
            if (Name != null)
                return Name;
            else
                return BaseName;
        }
    }

    public IEnumerable<XmlCommentSection> XmlCommentSections
    {
        get
        {
            if (Xml == null)
                yield break;
            XmlReaderSettings settings = new XmlReaderSettings();
            settings.IgnoreComments = true;
            settings.ConformanceLevel = ConformanceLevel.Fragment;
            settings.LineNumberOffset = FirstXmlComment.GetLineNumber() - 1;
            using (StringReader stringReader = new StringReader(Xml))
            {
                using (XmlReader xmlReader = XmlReader.Create(stringReader,
                        settings))
                {
                    while (true)
                    {
                        try
                        {
                            if (!xmlReader.Read())
                                break;
                        }
                        catch (XmlException ex)
                        {
                            throw NewParsingException(
                                Resources.InvalidXmlComment, ex.Message);
                        }

                        if (xmlReader.NodeType == XmlNodeType.Element)
                        {
                            // this XML element should be an XML comment
                            // section start element such as "<summary>" or
                            // "<param>"
                            XmlCommentSection section =
                                new XmlCommentSection(this, xmlReader);
                            yield return section;
                            try
                            {
                                section.ReadToEnd();
                            }
                            catch (XmlException ex)
                            {
                                throw NewParsingException(
                                    Resources.InvalidXmlComment, ex.Message);
                            }
                        }
                        else
                        if (xmlReader.NodeType == XmlNodeType.Text)
                        {
                            // there shouldn't be any text outside of XML
                            // comment sections
                            throw NewParsingException(xmlReader,
                                Resources.TextOutsideXmlCommentSection,
                                SourceFile.Ellipsis(xmlReader.Value, 50));
                        }
                    }
                }
            }
        }
    }

    public bool HasSummaryHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Summary);
        }
    }

    public bool HasReturnsHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Returns);
        }
    }

    public bool HasValueHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Value);
        }
    }

    public bool HasExceptionsHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Exception);
        }
    }

    public bool HasPermissionsHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Permission);
        }
    }

    public bool HasRemarksHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Remarks);
        }
    }

    public bool HasExampleHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.Example);
        }
    }

    public bool HasSeeAlsoHtml
    {
        get
        {
            return HasXmlCommentSectionHtml(XmlCommentSectionKind.SeeAlso);
        }
    }

    public bool IsExternallyAccessible
    {
        get
        {
            OverloadListTopic overloadListTopic;
            if ((overloadListTopic = this as OverloadListTopic) != null)
            {
                // overload list topics are accessible if at least one of their
                // overload topics are accessible
                foreach (Topic topic in overloadListTopic.OverloadTopics)
                {
                    if (topic.IsExternallyAccessible)
                        return true;
                }
                return false;
            }
            else
            {
                // regular topics are accessible based on their modifiers and
                // their ancestors' modifiers
                Topic topic = this;
                while (true)
                {
                    bool isInterfaceMember =
                        ((topic.ParentTopic != null) &&
                         (topic.ParentTopic.TopicKind ==
                          TopicKind.InterfaceTopic));
                    if (!topic.HasModifier("public", "protected") &&
                        !isInterfaceMember)
                        return false;
                    topic = topic.ParentTopic;
                    if (topic == null)
                        break;
                    if (topic.TopicKind == TopicKind.NamespaceTopic)
                        break;
                }
                return true;
            }
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public void SortChildTopics()
    {
        if (m_childTopics != null)
            m_childTopics.Sort();
    }

    public int GetDeclarationLineNumber()
    {
        Debug.Assert(StartOfDeclaration != null);
        if (StartOfDeclaration == null) // just in case
            return 0;
        else
            return StartOfDeclaration.GetLineNumber();
    }

    public override string ToString()
    {
        return QualifiedMemberName.ToString();
    }

    public static TokenList CanonicalizeMemberName(
        TokenList memberName, bool removeTrailingTypeParameters)
    {
        // do nothing if <memberName> is null
        if (memberName == null)
            return null;

        // if <memberName> doesn't contain type parameters, return it
        // as-is
        if (memberName.HeadToken.Next.FindCharacterToken(
                SourceFile.LAngle) == null)
            return memberName;

        // set <result> to a copy of <memberName> with type parameter
        // names removed
        TokenList result = new TokenList();
        int angleNesting = 0; // in "<...>"
        int squareNesting = 0; // in "[...]" -- ignore arrays, e.g. "[,]"
        Token trailingTypeParameter = null;
        foreach (Token token in memberName)
        {
            if (token.IsCharacter(SourceFile.LAngle))
            {
                if (angleNesting == 0)
                {
                    Token newToken = new Token(SourceFile.LAngle);
                    trailingTypeParameter = newToken;
                    result.Append(newToken);
                }
                angleNesting++;
            }
            else
            if (token.IsCharacter(SourceFile.RAngle))
            {
                angleNesting--;
                if (angleNesting == 0)
                    result.Append(new Token(SourceFile.RAngle));
            }
            else
            if (token.IsCharacter(SourceFile.LSquare))
                squareNesting++;
            else
            if (token.IsCharacter(SourceFile.RSquare))
                squareNesting--;
            else
            if (angleNesting == 0)
            {
                result.Append(token.Clone());
                trailingTypeParameter = null;
            }
            else
            if (token.IsCharacter(',') && (squareNesting == 0) &&
                    (angleNesting == 1))
                result.Append(token.Clone());
        }
        Debug.Assert(angleNesting == 0);
        Debug.Assert(squareNesting == 0);

        // remove trailing type parameters, if any (if specified)
        if (removeTrailingTypeParameters &&
            (trailingTypeParameter != null) &&
            !trailingTypeParameter.Next.IsTail)
        {
            TokenList.ExtractTokens(trailingTypeParameter,
                result.TailToken.Previous);         
        }

        return result;
    }

    public static string CanonicalizeMemberName(
        string memberName, bool removeTrailingTypeParameters)
    {
        // do nothing if <memberName> is null
        if (memberName == null)
            return null;

#if false
        // if <memberName> doesn't contain type parameters, return it
        // as-is
        if (memberName.IndexOf(SourceFile.LAngle) < 0)
            return memberName;
#endif

        // set <result> to a copy of <memberName> with type parameter
        // names removed
        StringBuilder result = new StringBuilder(memberName.Length);
        int angleNesting = 0; // in "<...>"
        int squareNesting = 0; // in "[...]" -- ignore arrays, e.g. "[,]"
        int trailingTypeParameterIndex = -1;
        foreach (char ch in memberName)
        {
            if (ch == SourceFile.LAngle)
            {
                if (angleNesting == 0)
                {
                    trailingTypeParameterIndex = result.Length;
                    result.Append(ch);
                }
                angleNesting++;
            }
            else
            if (ch == SourceFile.RAngle)
            {
                angleNesting--;
                if (angleNesting == 0)
                    result.Append(ch);
            }
            else
            if (ch == SourceFile.LSquare)
                squareNesting++;
            else
            if (ch == SourceFile.RSquare)
                squareNesting--;
            else
            if (angleNesting == 0)
            {
                result.Append(ch);
                trailingTypeParameterIndex = -1;
            }
            else
            if ((ch == ',') && (squareNesting == 0) && (angleNesting == 1))
                result.Append(ch);
        }
        Debug.Assert(angleNesting == 0);
        Debug.Assert(squareNesting == 0);

        // remove trailing type parameters, if any (and if specified); return
        // the result
        string resultString = result.ToString();
        if (removeTrailingTypeParameters)
        {
            if (trailingTypeParameterIndex >= 0)
                return resultString.Substring(0, trailingTypeParameterIndex);
            else
                return resultString;
        }
        else
            return resultString;
    }

    public static IEnumerable<Topic> EnumerateDescendentNonTypes(Topic topic)
    {
        // yield members of this type topic, but skip type topics
        // since we're already enumerating through all type topics
        foreach (Topic childTopic in topic.ChildTopics)
        {
            if (!childTopic.IsTypeTopic)
            {
                yield return childTopic;
                EnumerateDescendentNonTypes(topic);
            }
        }
    }

    public bool HasModifier(params string[] modifiers)
    {
        if (m_modifiers == null)
            return false;
        foreach (Token token in m_modifiers)
        {
            foreach (string modifier in modifiers)
            {
                if (token.IsWordOrReservedWord(modifier))
                    return true;
            }
        }
        return false;
    }

    public bool HasParameter(string parameterName)
    {
        if (Parameters == null)
            return false;
        return (m_parameters.Find(delegate(Parameter parameter)
        {
            return (parameter.ParameterName == parameterName);
        }) != null);
    }

    public Parameter GetParameter(string parameterName)
    {
        if (m_parameters == null)
            return null;
        return m_parameters.Find(delegate(Parameter parameter)
        {
            return (parameter.ParameterName == parameterName);
        });
    }

    public string GetParameterHtml(string parameterName)
    {
        // do nothing if there is no HTML for any XML comment section
        if (m_xmlSectionsHtml == null)
            return null;

        // set <paramSection> to the "<param>" XmlCommentSection that has a
        // "name" attribute equal to <parameterName>, or null if none
        List<XmlCommentSection> paramSections =
                m_xmlSectionsHtml[(int) XmlCommentSectionKind.Param];
        if (paramSections == null)
            return null;
        XmlCommentSection paramSection = paramSections.Find(
            delegate(XmlCommentSection section)
            {
                return (section.NameAttribute == parameterName);
            });

        // return the HTML of <paramSection>, if any
        if (paramSection != null)
            return paramSection.Html.Trim();
        else
            return null;
    }

    public bool HasTypeParameter(string typeParameterName)
    {
        if (TypeParameters == null)
            return false;
        return (Array.Find(TypeParameters, delegate(TokenList typeParameter)
        {
            return (typeParameter.ToString() == typeParameterName);
        }) != null);
    }

    public string GetTypeParameterHtml(string typeParameterName)
    {
        // do nothing if there is no HTML for any XML comment section
        if (m_xmlSectionsHtml == null)
            return null;

        // set <typeParamSection> to the "<typeparam>" XmlCommentSection that
        // has a "name" attribute equal to <typeParameterName>, or null if none
        List<XmlCommentSection> typeParamSections =
                m_xmlSectionsHtml[(int) XmlCommentSectionKind.TypeParam];
        if (typeParamSections == null)
            return null;
        XmlCommentSection typeParamSection = typeParamSections.Find(
            delegate(XmlCommentSection section)
            {
                return (section.NameAttribute == typeParameterName);
            });

        // return the HTML of <typeParamSection>, if any
        if (typeParamSection != null)
            return typeParamSection.Html.Trim();
        else
            return null;
    }

    public void AddXmlSectionHtml(XmlCommentSection section, string html)
    {
        // store <html> in section>
        section.Html = html;

        // create <m_xmlSectionsHtml> if it hasn't been created yet
        if (m_xmlSectionsHtml == null)
        {
            m_xmlSectionsHtml =
                new List<XmlCommentSection>[(int) XmlCommentSectionKind.Length];
        }

        // create the appropriate element of <m_xmlSectionsHtml> if it hasn't
        // been created yet
        int sectionKindInt = (int) section.SectionKind;
        List<XmlCommentSection> list = m_xmlSectionsHtml[sectionKindInt];
        if (list == null)
        {
            list = new List<XmlCommentSection>();
            m_xmlSectionsHtml[sectionKindInt] = list;
        }

        // add <section> to the list
        section.Enumerating = false;
        list.Add(section);
    }

    public void WriteSummaryHtml(HtmlTextWriter htmlWriter)
    {
        WriteXmlCommentSectionHtml(XmlCommentSectionKind.Summary, htmlWriter,
            null);
    }

    public void WriteReturnsHtml(HtmlTextWriter htmlWriter)
    {
        WriteXmlCommentSectionHtml(XmlCommentSectionKind.Returns, htmlWriter,
            null);
    }

    public void WriteValueHtml(HtmlTextWriter htmlWriter)
    {
        WriteXmlCommentSectionHtml(XmlCommentSectionKind.Value, htmlWriter,
            null);
    }

    public void WriteSummaryHtml(HtmlTextWriter htmlWriter,
        HtmlTextWriterDelegate htmlWriterDelegate)
    {
        WriteXmlCommentSectionHtml(XmlCommentSectionKind.Summary, htmlWriter,
            htmlWriterDelegate);
    }

    public void WriteRemarksHtml(HtmlTextWriter htmlWriter)
    {
        WriteXmlCommentSectionHtml(XmlCommentSectionKind.Remarks, htmlWriter,
            null);
    }

    public void WriteExampleHtml(HtmlTextWriter htmlWriter)
    {
        WriteXmlCommentSectionHtml(XmlCommentSectionKind.Example, htmlWriter,
            null);
    }

    public bool HasXmlCommentSectionHtml(XmlCommentSectionKind sectionKind)
    {
        if (m_xmlSectionsHtml == null)
            return false;
        List<XmlCommentSection> sections =
            m_xmlSectionsHtml[(int) sectionKind];
        return (sections != null) && (sections.Count > 0);
    }

    public IEnumerable<XmlCommentSection> GetRenderedXmlCommentSections(
        XmlCommentSectionKind sectionKind)
    {
        // do nothing if there is no array of XML comment section HTML
        if (m_xmlSectionsHtml == null)
            yield break;

        // set <sections> to the list of sections of this type; do nothing if
        // there is none
        List<XmlCommentSection> sections =
            m_xmlSectionsHtml[(int) sectionKind];
        if ((sections == null) || (sections.Count == 0))
            yield break;

        // yield each section
        foreach (XmlCommentSection section in sections)
            yield return section;
    }

    public void WriteXmlCommentSectionHtml(XmlCommentSectionKind sectionKind,
        HtmlTextWriter htmlWriter, HtmlTextWriterDelegate htmlWriterDelegate)
    {
        foreach (XmlCommentSection section in 
            GetRenderedXmlCommentSections(sectionKind))
        {
            htmlWriter.RenderBeginTag("p");
            string innerHtml = section.Html.Trim();
            htmlWriter.Write(innerHtml);
            if (htmlWriterDelegate != null)
                htmlWriterDelegate(htmlWriter);
            htmlWriter.RenderEndTag();
            htmlWriter.WriteLine();
        }
    }

#if DEBUG
    /// <summary>
    /// Returns debugging information about this topic.
    /// </summary>
    ///
    /// <param name="maxDataLength">Each piece of output data is truncated to
    ///     approximately this length.</param>
    ///
    public string Dump(int maxDataLength)
    {
        StringBuilder result = new StringBuilder(1000);

        result.AppendFormat("----- {0} {1} -----\r\n", TopicKind,
            QualifiedMemberName);

        if (MethodKind != MethodKind.NotAMethod)
            result.AppendFormat("MethodKind: {0}\r\n", MethodKind);

        if (PropertyKind != PropertyKind.NotAProperty)
            result.AppendFormat("PropertyKind: {0}\r\n", PropertyKind);

        if (Attributes != null)
        {
            result.Append("Attributes: ");
            int length = 0;
            foreach (TokenList attribute in Attributes)
            {
                string str = "[" + attribute.ToString() + "]";
                int newLength = length + str.Length;
                if (newLength > maxDataLength)
                {
                    result.AppendFormat("{0}...",
                        str.Substring(0, maxDataLength - length));
                    break;
                }
                else
                    result.Append(str);
                length = newLength;
            }
            result.Append("\r\n");
        }

        if (Modifiers != null)
        {
            result.AppendFormat("Modifiers: {0}\r\n",
                TokenList.ToString(Modifiers, maxDataLength, false));
        }

        if (MemberType != null)
        {
            result.AppendFormat("MemberType: {0}\r\n",
                TokenList.ToString(MemberType, maxDataLength, false));
        }

        if (NamespaceName != null)
            result.AppendFormat("NamespaceName: {0}\r\n", NamespaceName);

        if (ParentTypeName != null)
            result.AppendFormat("ParentTypeName: {0}\r\n", ParentTypeName);

        if (ExplicitPrefix != null)
        {
            result.AppendFormat("ExplicitPrefix: {0}\r\n",
                TokenList.ToString(ExplicitPrefix, maxDataLength, false));
        }

        result.AppendFormat("MemberName: {0}\r\n", MemberName);

        if (TypeParameters != null)
        {
            result.AppendFormat("TypeParameters: <{0}>\r\n",
                TokenList.Join(',', TypeParameters)
                    .ToString(maxDataLength, false, false));
        }

        if (BaseTypes != null)
        {
            TokenList separator = new TokenList();
            separator.Append(new Token(','));
            separator.Append(new Token(TokenType.WhiteSpace, " "));
            result.AppendFormat("BaseTypes: {0}\r\n",
                TokenList.JoinWithSeparator(separator, BaseTypes)
                    .ToString(maxDataLength, false, false));
        }

        if (BaseClassTopic != null)
            result.AppendFormat("BaseClassTopic: {0}\r\n", BaseClassTopic);

        if (Parameters != null)
        {
            StringBuilder data = new StringBuilder(200);
            foreach (Parameter parameter in Parameters)
            {
                if (data.Length == 0)
                    data.Append(parameter.ToString());
                else
                    data.AppendFormat(", {0}", parameter);
                if (data.Length > maxDataLength)
                    break;
            }
            result.Append("Parameters: ");
            if (data.Length > maxDataLength)
            {
                result.AppendFormat("{0}...",
                    data.ToString().Substring(0, maxDataLength - data.Length));
            }
            else
                result.Append(data.ToString());
            result.Append("\r\n");
        }

        if (Constraints != null)
        {
            result.AppendFormat("Constraints: {0}\r\n",
                TokenList.ToString(Constraints, maxDataLength, false));
        }

        if (GetAccessor != null)
            result.AppendFormat("GetAccessor: {0}\r\n", GetAccessor);

        if (SetAccessor != null)
            result.AppendFormat("SetAccessor: {0}\r\n", SetAccessor);

        if (EnumValueNamesArray != null)
        {
            result.AppendFormat("EnumValueNames: {0}\r\n",
                SourceFile.Ellipsis(String.Join(
                    ", ", EnumValueNamesArray), maxDataLength));
        }

        result.AppendFormat("Xml: {0}\r\n", SourceFile.Ellipsis(Xml,
            maxDataLength));

#if false
        result.Append(UsingContext.Dump());
#endif

        return result.ToString();
    }
#endif

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal Topic(SourceFile sourceFile)
    {
        m_sourceFile = sourceFile;
    }

    internal void AddChildTopic(Topic childTopic)
    {
        if (m_childTopics == null)
            m_childTopics = new List<Topic>(20);
        m_childTopics.Add(childTopic);
    }

    internal new Topic MemberwiseClone()
    {
        return (Topic) base.MemberwiseClone();
    }

    internal void PrevalidateXmlComment()
    {
        foreach (XmlCommentSection section in XmlCommentSections)
        {
            using (XmlReader xmlReader = section.GetXmlReader())
            {
                while (xmlReader.Read())
                    ;
            }

        }
    }

    internal ParsingException NewParsingException(
        string format, params object[] args)
    {
        return new ParsingException(SourceFile.SourceFileAbsolutePath,
            FirstXmlComment.GetLineNumber(), format, args);
    }

    internal ParsingException NewParsingException(
        XmlReader xmlReader, string format, params object[] args)
    {
        return new ParsingException(SourceFile.SourceFileAbsolutePath,
            ((IXmlLineInfo) xmlReader).LineNumber, format, args);
    }

    internal static string MakeValidFileName(string name)
    {
        name = name.Replace(SourceFile.LAngle, SourceFile.LSquare)
                   .Replace(SourceFile.RAngle, SourceFile.RSquare);
        return s_nonFileNameCharRegex.Replace(name, delegate(Match match)
        {
            Debug.Assert(match.Value.Length == 1);
            char ch = match.Value[0];
            if (ch < 0x100)
            {
                // replace ASCII characters with "$xx" (2-byte hex value)
                return String.Format("${0:X2}", (int) ch);
            }
            else
            {
                // replace non-ASCII Unicode characters with "$uXXXX" (4-byte
                // hex value)
                return String.Format("$u{0:X4}", (int) ch);
            }
        });
    }

    //////////////////////////////////////////////////////////////////////////
    // Private Methods
    //

    public bool CopyTypeName(TokenList tokenList)
    {
        // do nothing if this isn't a type topic
        if (TopicKind == TopicKind.NamespaceTopic)
            return false;

        // recurse to add the ancesor types to <tokenList>
        if (ParentTopic != null)
        {
            if (ParentTopic.CopyTypeName(tokenList))
                tokenList.Append(new Token('.'));
        }

        // add the member name to <tokenList>
        tokenList.Append(new Token(TokenType.Word, MemberName));

        // add type parameters, if any
        if (TypeParameters != null)
        {
            tokenList.Append(new Token(SourceFile.LAngle));
            bool first = true;
            foreach (TokenList typeParameter in TypeParameters)
            {
                if (first)
                    first = false;
                else
                    tokenList.Append(new Token(','));
                tokenList.AppendCopy(typeParameter);
            }
            tokenList.Append(new Token(SourceFile.RAngle));
        }

        return true;
    }

    void ConstructQualifiedMemberName(TokenList result, bool includeNamespace,
        bool includeParentType, bool includeExplicitPrefix)
    {
        if ((m_namespaceName != null) && includeNamespace)
        {
            foreach (Token token in m_namespaceName)
                result.Append(token.Clone());
        }
        if (includeParentType)
        {
            TokenList parentTypeName = ParentTypeName;
            if (parentTypeName != null)
            {
                if (!result.IsEmpty)
                    result.Append(new Token('.'));
                foreach (Token token in parentTypeName)
                    result.Append(token.Clone());
            }
        }
        if (m_memberName != null)
        {
            if (!result.IsEmpty)
                result.Append(new Token('.'));
            if (includeExplicitPrefix && (ExplicitPrefix != null))
                result.AppendCopy(ExplicitPrefix);
            result.Append(new Token(TokenType.Word, m_memberName));
        }
    }

    string GetTitle(string memberName, bool includeTopicKind)
    {
        StringBuilder result = new StringBuilder(200);
        result.Append(memberName);
        if ((TypeParameters != null) && (OverloadListTopic != null))
        {
            result.AppendFormat("<{0}>", TokenList.Join(',', TypeParameters)
                .ToString(int.MaxValue, false, false));
        }
        if (includeTopicKind)
        {
            if (TopicKind == TopicKind.MethodTopic)
            {
                if (MethodKind == MethodKind.Constructor)
                    result.AppendFormat(" {0}", Resources.Constructor);
                else
                if (MethodKind == MethodKind.Destructor)
                    result.AppendFormat(" {0}", Resources.Destructor);
                else
                    result.AppendFormat(" {0}", TopicKindTitle);
            }
            else
                result.AppendFormat(" {0}", TopicKindTitle);
        }
        if ((Parameters != null) && (OverloadListTopic != null))
        {
            result.Append(" (");
            bool firstParameter = true;
            foreach (Parameter parameter in Parameters)
            {
                if (firstParameter)
                    firstParameter = false;
                else
                    result.Append(", ");
                string kind = parameter.CSharpKind;
                if (kind != null)
                    result.AppendFormat("{0} ", kind);
                result.Append(parameter.ParameterType.ToString());
            }
            result.Append(")");
        }
        return result.ToString();
    }

    string GetOverloadingSignature()
    {
        // return null if this topic isn't an overloadable member
        if (TopicKind == TopicKind.PropertyTopic)
        {
            // all properties are overloadable
        }
        else
        if (TopicKind == TopicKind.MethodTopic)
        {
            // methods are overloadable except constructors and destructors
            if ((MethodKind == MethodKind.Constructor) ||
                (MethodKind == MethodKind.Destructor))
                return null;
        }
        else
        if (TopicKind == TopicKind.EventTopic)
        {
            // all events are overloadable
        }
        else
            return null; // not overloadable

        // the return value will be accumulated into <result>
        StringBuilder result = new StringBuilder(500);

        // append the member name
        if (MemberName != null)
            result.Append(MemberName);

        // append type parameters, if any
        if (TypeParameters != null)
        {
            result.AppendFormat("<{0}>",
                TokenList.Join(',', TypeParameters)
                    .ToString(int.MaxValue, false, false));
        }

        // append regular parameters, if any; don't include "params"
        // declarations
        if (Parameters != null)
        {
            result.Append(SourceFile.LParen);
            bool first = true;
            foreach (Parameter parameter in Parameters)
            {
                if (first)
                    first = false;
                else
                    result.Append(", ");
                if ((parameter.ParameterKind != ParameterKind.Unknown) &&
                    (parameter.ParameterKind != ParameterKind.Normal) &&
                    (parameter.ParameterKind != ParameterKind.Params))
                    result.AppendFormat("{0} ", parameter.CSharpKind);
                result.Append(parameter.ParameterType);
            }
            result.Append(SourceFile.RParen);
        }

        // done
        return result.ToString();
    }

    //////////////////////////////////////////////////////////////////////////
    // IComparable Implementation
    //

    int IComparable<Topic>.CompareTo(Topic other)
    {
        return String.Compare(LongSignature, other.LongSignature, true);
    }
}

[DebuggerDisplay("{DebuggerDisplay}")]
public class NamespaceTopic : Topic
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<Topic> m_typeTopics = new List<Topic>(20);

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public IList<Topic> TypeTopics
    {
        [DebuggerStepThrough]
        get
        {
            return new ReadOnlyCollection<Topic>(m_typeTopics);
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public void SortTypeTopics()
    {
        if (m_typeTopics != null)
            m_typeTopics.Sort();
    }

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal NamespaceTopic(string namespaceName)
        : base(null)
    {
        MemberName = namespaceName;
    }

    internal void AddTypeTopic(Topic typeTopic)
    {
        Debug.Assert(TokenList.ToString(typeTopic.NamespaceName)
            == MemberName);
        m_typeTopics.Add(typeTopic);
        typeTopic.IsTypeTopic = true;
    }
}

Foo.Bar(int)
Foo.Bar(int, bool)

Foo<T>.Bar
Foo<T,U>.Bar

Foo<T>.Bar
Foo<T,U>.Bar(int)
Foo<T,U>.Bar(int, bool)

Foo<T>
Foo<T,U>

[DebuggerDisplay("{DebuggerDisplay}")]
public class OverloadListTopic : Topic
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<Topic> m_overloadTopics = new List<Topic>();

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public IList<Topic> OverloadTopics
    {
        [DebuggerStepThrough]
        get
        {
            return new ReadOnlyCollection<Topic>(m_overloadTopics);
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public void SortOverloadTopics()
    {
        if (m_overloadTopics != null)
            m_overloadTopics.Sort();
    }

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal OverloadListTopic()
        : base(null)
    {
    }

    internal void AddOverloadTopic(Topic overloadTopic)
    {
        Debug.Assert(overloadTopic.TopicKind == TopicKind);
        Debug.Assert(overloadTopic.NamespaceName == NamespaceName);
        Debug.Assert(overloadTopic.ParentTypeName == ParentTypeName);
        Debug.Assert(overloadTopic.MemberName == MemberName);
        m_overloadTopics.Add(overloadTopic);
    }
}

public enum TopicKind
{

    UnknownTopic,

    NamespaceTopic,

    ClassTopic,

    StructTopic,

    InterfaceTopic,

    EventTopic,

    DelegateTopic,

    EnumTopic,

    EnumValueTopic,

    MethodTopic,

    PropertyTopic,

    FieldTopic,
}

public enum MethodKind
{

    NotAMethod = 0,

    Normal,

    Constructor,

    Destructor,

    Operator,
}

public enum PropertyKind
{

    NotAProperty = 0,

    Normal,

    Indexer,
}

[DebuggerDisplay("{DebuggerDisplay}")]
public class Parameter
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    ParameterKind m_parameterKind;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_parameterType;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_parameterName;

    //////////////////////////////////////////////////////////////////////////
    // Private Properties
    //

#if DEBUG
    /// <summary>
    /// Gets a string displayed in the debugger.
    /// </summary>
    public string DebuggerDisplay
    {
        get
        {
            return ToString();
        }
    }
#endif

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public ParameterKind ParameterKind
    {
        [DebuggerStepThrough]
        get
        {
            return m_parameterKind;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_parameterKind = value;
        }
    }

    public TokenList ParameterType
    {
        [DebuggerStepThrough]
        get
        {
            return m_parameterType;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_parameterType = value;
        }
    }

    public string ParameterName
    {
        [DebuggerStepThrough]
        get
        {
            return m_parameterName;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_parameterName = value;
        }
    }

    public string CSharpKind
    {
        get
        {
            switch (m_parameterKind)
            {
            case ParameterKind.Out:
                return "out";
            case ParameterKind.Ref:
                return "ref";
            case ParameterKind.Params:
                return "params";
            default:
                return null;
            }
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public override string ToString()
    {
        StringBuilder result = new StringBuilder(200);
        string kind = CSharpKind;
        if (kind != null)
            result.AppendFormat("{0} ", kind);
        result.Append(ParameterType.ToString());
        result.Append(' ');
        result.Append(ParameterName);
        return result.ToString();
    }

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal Parameter()
    {
    }
}

public enum ParameterKind
{

    Unknown = 0,

    Normal,

    Out,

    Ref,

    Params,
}

[DebuggerDisplay("{DebuggerDisplay}")]
public class Accessor
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    AccessorKind m_accessorKind;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    TokenList m_accessorModifiers;

    //////////////////////////////////////////////////////////////////////////
    // Private Properties
    //

#if DEBUG
    /// <summary>
    /// Gets a string displayed in the debugger.
    /// </summary>
    public string DebuggerDisplay
    {
        get
        {
            return ToString();
        }
    }
#endif

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public AccessorKind AccessorKind
    {
        [DebuggerStepThrough]
        get
        {
            return m_accessorKind;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_accessorKind = value;
        }
    }

    public TokenList AccessorModifiers
    {
        [DebuggerStepThrough]
        get
        {
            return m_accessorModifiers;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_accessorModifiers = value;
        }
    }

    public bool HasModifier(params string[] modifiers)
    {
        if (m_accessorModifiers == null)
            return false;
        foreach (Token token in m_accessorModifiers)
        {
            foreach (string modifier in modifiers)
            {
                if (token.IsWordOrReservedWord(modifier))
                    return true;
            }
        }
        return false;
    }

    public bool IsExternallyAccessible
    {
        get
        {
            // if no modifiers are specified, default to public access
            if (AccessorModifiers == null)
                return true;

            // otherwise, the accessor is only externally accessible if its
            // modifiers include "protected" -- see section 25.1.1 of the C#
            // Language Specification 2.0
            return HasModifier("protected");
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public override string ToString()
    {
        StringBuilder result = new StringBuilder(200);
        if (AccessorModifiers != null)
            result.Append(AccessorModifiers.ToString());
        if (result.Length != 0)
            result.Append(' ');
        if (AccessorKind == AccessorKind.Get)
            result.Append("get");
        else
        if (AccessorKind == AccessorKind.Set)
            result.Append("set");
        else
            Debug.Assert(false);
        return result.ToString();
    }

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal Accessor()
    {
    }
}

public enum AccessorKind
{

    Unknown = 0,

    Get,

    Set,
}

[DebuggerDisplay("XmlCommentSection: {SectionKind}")]
public class XmlCommentSection
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    static Dictionary<string, XmlCommentSectionKind> s_sectionKindDictionary =
        InitializeSectionKindDictionary();

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_topic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    XmlCommentSectionKind m_sectionKind;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_sectionName;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_nameAttribute;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_crefAttribute;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_hrefAttribute;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_html;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    bool m_enumerating;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    int m_lineNumber;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_referencedTopic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    XmlReader m_xmlReader;

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public Topic Topic
    {
        [DebuggerStepThrough]
        get
        {
            return m_topic;
        }
    }

    public XmlCommentSectionKind SectionKind
    {
        [DebuggerStepThrough]
        get
        {
            return m_sectionKind;
        }
    }

    public string SectionName
    {
        [DebuggerStepThrough]
        get
        {
            return m_sectionName;
        }
    }

    public string NameAttribute
    {
        [DebuggerStepThrough]
        get
        {
            return m_nameAttribute;
        }
        [DebuggerStepThrough]
        set
        {
            m_nameAttribute = value;
        }
    }

    public string CrefAttribute
    {
        [DebuggerStepThrough]
        get
        {
            return m_crefAttribute;
        }
        [DebuggerStepThrough]
        set
        {
            m_crefAttribute = value;
        }
    }

    public string HrefAttribute
    {
        [DebuggerStepThrough]
        get
        {
            return m_hrefAttribute;
        }
        [DebuggerStepThrough]
        set
        {
            m_hrefAttribute = value;
        }
    }

    public string Html
    {
        [DebuggerStepThrough]
        get
        {
            return m_html;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_html = value;
        }
    }

    public bool Enumerating
    {
        [DebuggerStepThrough]
        get
        {
            return m_enumerating;
        }
        [DebuggerStepThrough]
        internal set
        {
            m_enumerating = value;
        }
    }

    public int LineNumber
    {
        [DebuggerStepThrough]
        get
        {
            return m_lineNumber;
        }
        [DebuggerStepThrough]
        set
        {
            m_lineNumber = value;
        }
    }

    public Topic ReferencedTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_referencedTopic;
        }
        [DebuggerStepThrough]
        set
        {
            m_referencedTopic = value;
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    public XmlReader GetXmlReader()
    {
        if (m_xmlReader == null)
            throw new InvalidOperationException(Resources.NotEnumerating);
        return m_xmlReader.ReadSubtree();
    }

#if false
    /// <summary>
    /// Disconnects this <r>XmlCommentSection</r> object from the object that
    /// created it, so that this <r>XmlCommentSection</r> object can safely
    /// be added to a list.
    /// </summary>
    ///
    /// <remarks>
    /// Once <r>Disconnect</r> is called, <r>GetXmlReader</r> can no longer be
    /// called.
    /// </remarks>
    ///
    public void Disconnect()
    {
        m_xmlReader = null;
    }
#endif

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal XmlCommentSection(Topic topic, XmlReader xmlReader)
    {
        // note: <topic> may not be fully initialized -- use with caution
        m_topic = topic;
        m_xmlReader = xmlReader;
        Debug.Assert(xmlReader.NodeType == XmlNodeType.Element);
        m_sectionName = xmlReader.Name;
        if (!s_sectionKindDictionary.TryGetValue(m_sectionName,
            out m_sectionKind))
        {
            throw topic.NewParsingException(xmlReader,
                Resources.UnknownXmlCommentSection, m_sectionName);
        }
    }

    internal void ReadToEnd()
    {
        while (true)
        {
            if (((m_xmlReader.NodeType == XmlNodeType.EndElement) ||
                 m_xmlReader.IsEmptyElement) &&
                (m_xmlReader.Name == m_sectionName) &&
                (m_xmlReader.Depth == 0))
                break;
            if (!m_xmlReader.Read())
                break;
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Private Methods
    //

    static Dictionary<string, XmlCommentSectionKind>
        InitializeSectionKindDictionary()
    {
        // could have used Enum.Parse(), but that's a bit hacky and slow
        Dictionary<string, XmlCommentSectionKind> dictionary =
            new Dictionary<string, XmlCommentSectionKind>();
        dictionary.Add("summary", XmlCommentSectionKind.Summary);
        dictionary.Add("param", XmlCommentSectionKind.Param);
        dictionary.Add("typeparam", XmlCommentSectionKind.TypeParam);
        dictionary.Add("returns", XmlCommentSectionKind.Returns);
        dictionary.Add("value", XmlCommentSectionKind.Value);
        dictionary.Add("remarks", XmlCommentSectionKind.Remarks);
        dictionary.Add("example", XmlCommentSectionKind.Example);
        dictionary.Add("exception", XmlCommentSectionKind.Exception);
        dictionary.Add("permission", XmlCommentSectionKind.Permission);
        dictionary.Add("seealso", XmlCommentSectionKind.SeeAlso);
        return dictionary;
    }
}

[DebuggerDisplay("MemberInfo: {Topic}")]
public class MemberInfo : IComparable<MemberInfo>
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_topic;

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_inheritedFromTopic;

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    public Topic Topic
    {
        [DebuggerStepThrough]
        get
        {
            return m_topic;
        }
    }

    public Topic InheritedFromTopic
    {
        [DebuggerStepThrough]
        get
        {
            return m_inheritedFromTopic;
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Internal Methods
    //

    internal MemberInfo(Topic topic, Topic inheritedFromTopic)
    {
        m_topic = topic;
        m_inheritedFromTopic = inheritedFromTopic;
    }

    //////////////////////////////////////////////////////////////////////////
    // IComparable<T> Implementation
    //

    int IComparable<MemberInfo>.CompareTo(MemberInfo other)
    {
        return String.Compare(Topic.VeryShortTitleNoKind, other.Topic.VeryShortTitleNoKind, true);
    }
}

public enum XmlCommentSectionKind
{

    Summary = 0,

    Param = 1,

    TypeParam = 2,

    Returns = 3,

    Value = 4,

    Remarks = 5,

    Example = 6,

    Exception = 7,

    Permission = 8,

    SeeAlso = 9,

    /* if you update this list, update InitializeSectionKindDictionary() */

    Length = 10/*must be equal to highest-numbered value plus one*/,
}

public delegate void HtmlTextWriterDelegate(HtmlTextWriter writer);

}