GhostDoc Breaks SyntaxHighlighter

Leveraging tools is a great way to be more productive. Two tools that I regularly use are GhostDoc and SyntaxHighlighter. Sometimes one tool will cause another tools to break. Before getting into why GhostDoc causes SyntaxHighlighter to break, let’s give each tool a bit of spotlight.

Update: After doing a little investigating on the SyntaxHighlighter website, I noticed there is a new format for the <pre> tags. I updated my PreCode plugin for Live Writer to emit the new tags and this issue is gone! Looks like the folks developing SyntaxHighlighter have already addressed this issue. Here is a sample with the GhostDoc comments being rendered correctly.

/// <summary>
/// Logs the entry view.
/// </summary>
/// <param name="entryId">The entry id.</param>
/// <param name="entryTitle">The entry title.</param>
public static void LogEntryView(string entryId, string entryTitle)
{
    // Get this user's IP address and log
    //
    string ipAddress = HttpContext.Current.Request.ServerVariables["REMOTE_ADDR"];
    Rlc.Utilities.Web.IpLocator.Location location = new Rlc.Utilities.Web.IpLocator.Location();
    location.Status = false;
    if (!string.IsNullOrEmpty(ipAddress))
    {
        location = Rlc.Utilities.Web.IpLocator.Find(ipAddress);
    }
    string info = string.Format("Location: {0}, Title: {1}, ID: {2}", location, entryTitle, entryId);
    Rlc.Utilities.Logging.Logger.LogStatus("Entry", info);
}

GhostDoc

GhostDoc is a Visual Studio add-in created by Roland Weiglt. It automatically generates XML documentation comments for C#. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters. Below is an image showing GhostDoc’s handy work:

The comment section in the red square is generated automatically by GhostDoc when I press CTRL-SHIFT-D on the method. The stubbed in version created by GhostDoc may require some additional information, but it is generally quite good.

SyntaxHighlighter

SytaxHighlighter is a JavaScript library created by Alex Gorbatchev. It is a fully functional self-contained code syntax highlighter. This library parses through your html looking for text surrounded by <pre> tags. This is an example:

The library then provides additional markup so the text gets rendered like this:

The library adds a lot of HTML tags and CSS to make this happen. The final markup for the above code snippet is shown here:

By the way don’t try to use SyntaxHighlighter to display the above code.

Where Things Break Down

Things break down when you try to use SyntaxHighlighter to display a code snippet that includes the documentation generated by GhostDoc. The root cause is the “param” tag. I have submitted this improvement to the SyntaxHighligher website. For now, those of use that use both GhostDoc (2.1.3 for Visual Studio 2008) and SyntaxHighlighter (2.0.320) should be aware of this issue.