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

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

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

namespace DwellNet.CodeDoc
{
TopicRenderer Class

Converts a CodeDoc Topic to HTML.

 
public abstract class TopicRenderer
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //
    
TopicRenderer.m_topic Field

Holds the value of the Topic property.

 
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    Topic m_topic;
    
TopicRenderer.m_codeHtml Field

Holds the value of the CodeHtml property.

 
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    bool m_codeHtml;
    
TopicRenderer.m_markOfTheWeb Field

Holds the value of the MarkOfTheWeb property.

 
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    bool m_markOfTheWeb;
    
TopicRenderer.m_topicFooterHtml Field

Holds the value of the TopicFooterHtml property.

 
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    string m_topicFooterHtml;
    
TopicRenderer.m_hideAttributesRegexList Field

Holds the value of the HideAttributesRegexList property.

 
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    List<Regex> m_hideAttributesRegexList;

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //
    
TopicRenderer.Topic Property

Sets or gets the topic being rendered by this TopicRenderer.

 
    public Topic Topic
    {
        [DebuggerStepThrough]
        get
        {
            return m_topic;
        }
        [DebuggerStepThrough]
        set
        {
            m_topic = value;
        }
    }
    
TopicRenderer.CodeHtml Property

Sets or gets a value that's true to indicate that the topic being rendered will be used as a documentation block embedded within formatted source code pages (i.e. "<WriteFormattedCode>" in the CodeDoc XML project file), false if the topic will be used in a documentation page (i.e. "<WriteDocumentation>" in the CodeDoc XML project file).

 
    public bool CodeHtml
    {
        [DebuggerStepThrough]
        get
        {
            return m_codeHtml;
        }
        [DebuggerStepThrough]
        set
        {
            m_codeHtml = value;
        }
    }
    
TopicRenderer.MarkOfTheWeb Property

Gets or sets a value that indicates whether to include the Mark of the Web on generated HTML pages. See HtmlTextWriterHelper.BeginHtmlDocument for more information.

 
    public bool MarkOfTheWeb
    {
        [DebuggerStepThrough]
        get
        {
            return m_markOfTheWeb;
        }
        [DebuggerStepThrough]
        set
        {
            m_markOfTheWeb = value;
        }
    }
    
TopicRenderer.TopicFooterHtml Property

Gets or sets the footer HTML to use at the bottom of generated HTML pages; null if none.

 
    public string TopicFooterHtml
    {
        [DebuggerStepThrough]
        get
        {
            return m_topicFooterHtml;
        }
        [DebuggerStepThrough]
        set
        {
            m_topicFooterHtml = value;
        }
    }
    
TopicRenderer.HideAttributesRegexList Property

A list of regular expressions; if a regular expression matches an attribute (i.e. a declaration in [square brackets]), that attribute is not documented. Ignored if null.

 
    public List<Regex> HideAttributesRegexList
    {
        [DebuggerStepThrough]
        get
        {
            return m_hideAttributesRegexList;
        }
        [DebuggerStepThrough]
        set
        {
            m_hideAttributesRegexList = value;
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Events
    //
    
TopicRenderer.WarningInSourceFile Event

Fired to indicate a warning associated with a given line number in a source file.

Remarks

The application may want to use this event to provide feedback to the user.

 
    public event WarningInSourceFileEventDelegate WarningInSourceFile;

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //
    
TopicRenderer.CreateRenderer Method

Creates an instance of a topic renderer (i.e. a class derived from TopicRenderer) implemented in a given assembly (DLL).

Parameters

rendererAssemblyName

The name of the topic renderer assembly to use to generate documentation; for example, "CodeDocRenderer". This DLL should be located in the same directory as the application .exe file.

rendererTypeName

The fully-qualified name of the topic renderer class; for example, "DwellNet.CodeDoc.DefaultTopicRenderer". This class must be implemented in the topic renderer assembly specified by rendererAssemblyName. This class must derive from the TopicRenderer.

markOfTheWeb

true to include the Mark of the Web on rendered pages. See HtmlTextWriterHelper.BeginHtmlDocument for more information.

topicFooterHtml

The HTML to include at the bottom of rendered topic pages; null if none.

hideAttributesRegexList

A list of regular expressions; if a regular expression matches an attribute (i.e. a declaration in [square brackets]), that attribute is not documented. Ignored if null.

Return Value

The topic renderer.

Exceptions
Exception type Condition
CreateExternalObjectException

Caused by one of the following conditions:

  • the assembly specified by rendererAssemblyName could not be loaded;
  • the assembly specified by rendererAssemblyName does not contain the type specified by rendererTypeName;
  • an instance of the type specified by rendererTypeName could not be created;
  • the created instance of the type specified by rendererTypeName is not based on class TopicRenderer.
Remarks

The returned TopicRenderer may be used with GenerateDocHtmlInDirectory.

 
    public static TopicRenderer CreateRenderer(string rendererAssemblyName,
        string rendererTypeName, bool markOfTheWeb, string topicFooterHtml,
        List<Regex> hideAttributesRegexList)
    {
        TopicRenderer topicRenderer =
            DocumentationSet.CreateExternalObject<TopicRenderer>(
                rendererAssemblyName, rendererTypeName);
        topicRenderer.MarkOfTheWeb = markOfTheWeb;
        topicRenderer.TopicFooterHtml = topicFooterHtml;
        topicRenderer.HideAttributesRegexList = hideAttributesRegexList;
        return topicRenderer;
    }
    
TopicRenderer.GenerateDocHtml Method ()

Generates documentation HTML corresponding to Topic. Returns a string of HTML.

Remarks

As described in GenerateDocHtmlInDirectory and other overloads of GenerateDocHtml, documentation generation is a two-pass process. This method performs only the second pass; the caller is responsible for ensuring that the first pass has already been performed on all topics.

 
    public string GenerateDocHtml()
    {
        StringBuilder stringBuilder = new StringBuilder(2000);
        using (StringWriter stringWriter = new StringWriter(stringBuilder))
        {
            using (HtmlTextWriterHelper writer =
                    new HtmlTextWriterHelper(stringWriter))
                GenerateDocHtml(false, writer);
        }
        return stringBuilder.ToString();
    }
    
TopicRenderer.GenerateDocHtml Method (string)

Executes one of two documentation generation passes: In the first pass, each section (e.g. "<summary>") of a given Topic's Xml property is converted to HTML, accessible via Topic.WriteXmlCommentSectionHtml and related methods. In the second pass, HTML documentation for the topic is written to a specified file.

Parameters

path

For the first pass, this is null. For the second path, this is the path to the file to write to.

Remarks

The first pass of the documentation generation process must be peformed for all documentation topics before the second pass is performed on any topic.

The documentation file is overwritten if it already exists. 

    public void GenerateDocHtml(string path)
    {
        // make sure we have unique topic HTML file names etc.
        Topic.DocumentationSet.BeginUsingSources();

        // generate documentation HTML
        if (path == null)
        {
            // first pass
            GenerateDocHtml(false, (HtmlTextWriterHelper) null);
        }
        else
        {
            // second pass
            using (StreamWriter streamWriter = new StreamWriter(path))
            {
                using (HtmlTextWriterHelper writer =
                        new HtmlTextWriterHelper(streamWriter))
                    GenerateDocHtml(false, writer);
            }
        }
    }
    
TopicRenderer.GenerateDocHtmlInDirectory Method

Executes one of two documentation generation passes: In the first pass, each section (e.g. "<summary>") of a given Topic's Xml property is converted to HTML, accessible via Topic.WriteXmlCommentSectionHtml and related methods. In the second pass, HTML documentation for the topic is written to a file named by the value of property Topic.DocHtmlFileName, in a provided directory.

Parameters

topic

The topic to render.

docHtmlDirPath

The full path to the directory where the the documentation HTML file should be written; null for the first pass.

topicRenderer

The topic renderer to use to generate documentation. This object may be created by calling CreateRenderer.

Remarks

The first pass of the documentation generation process must be peformed for all documentation topics before the second pass is performed on any topic.

The documentation file is overwritten if it already exists. 

    public static void GenerateDocHtmlInDirectory(Topic topic,
        string docHtmlDirPath, TopicRenderer topicRenderer)
    {
        // make sure we have unique topic HTML file names etc.
        topic.DocumentationSet.BeginUsingSources();

        // initialize <topicRenderer>
        topicRenderer.Topic = topic;

        // generate documentation HTML
        if (docHtmlDirPath == null)
        {
            // first pass
            topicRenderer.GenerateDocHtml(false, (HtmlTextWriterHelper) null);
        }
        else
        {
            // second pass
            string docHtmlFilePath = Path.Combine(docHtmlDirPath,
                topic.DocHtmlFileName);
            using (StreamWriter streamWriter =
                new StreamWriter(docHtmlFilePath))
            {
                using (HtmlTextWriterHelper htmlWriter =
                    new HtmlTextWriterHelper(streamWriter))
                {
                    topicRenderer.GenerateDocHtml(false, htmlWriter);
                }
            }
        }
    }
    
TopicRenderer.GenerateDocHtml Method (bool, HtmlTextWriterHelper)

Executes one of two documentation generation passes: In the first pass, each section (e.g. "<summary>") of a given Topic's Xml property is converted to HTML, accessible via Topic.WriteXmlCommentSectionHtml and related methods. In the second pass, HTML documentation for the topic is written to an HtmlTextWriterHelper.

Parameters

embedded

If true "embedded" HTML is generated, i.e. a "<div>" designed to fit compactly within formatted source code. If false, a complete HTML document is generated. Ignored for the first pass.

htmlWriter

For the first pass, this is null. For the second path, this is the HtmlTextWriterHelper to write to.

Remarks

The first pass of the documentation generation process must be peformed for all documentation topics before the second pass is performed on any topic.

 
    public abstract void GenerateDocHtml(bool embedded,
        HtmlTextWriterHelper htmlWriter);
    
TopicRenderer.GenerateCodeNamespaceHtml Method

Assuming Topic is a namespace topic, this method generates the HTML file, used in the formatted code directory, that represents the namespace and contains links to the formatted code HTML files. list.

Parameters

htmlWriter

The HtmlTextWriterHelper to write to.

 
    public abstract void GenerateCodeNamespaceHtml(
        HtmlTextWriterHelper htmlWriter);
    
TopicRenderer.GenerateCodeOverloadListHtml Method

Assuming Topic is an overload list topic, this method generates the HTML file, used in the formatted code directory, that contains links to the documentation block of each overload topic in the overload list.

Parameters

htmlWriter

The HtmlTextWriterHelper to write to.

 
    public abstract void GenerateCodeOverloadListHtml(
        HtmlTextWriterHelper htmlWriter);

    //////////////////////////////////////////////////////////////////////////
    // Protected Methods
    //
    
TopicRenderer.FireWarningInSourceFile Method

Fires the WarningInSourceFile event.

Parameters

lineNumber

The line number within the source file that the warning relates to.

format

A String.Format-style format string used to format the warning message text.

args

Arguments for the format string.

 
    protected void FireWarningInSourceFile(int lineNumber, string format,
        params object[] args)
    {
        if (WarningInSourceFile != null)
        {
            WarningInSourceFile(Topic.SourceFile, lineNumber,
                String.Format(format, args));
        }
    }
}
WarningInSourceFileEventDelegate Delegate

The type of an event handler for an event which is fired to indicate a warning associated with a given line number in a source file.

Parameters

sourceFile

The souce file that the warning relates to.

lineNumber

The line number within the source file that the warning relates to.

message

The warning message text.

Remarks

See the TopicRenderer.WarningInSourceFile event.

 
public delegate void WarningInSourceFileEventDelegate(SourceFile sourceFile,
    int lineNumber, string message);

}