Quantcast
Channel: SharpDevelop Community
Viewing all articles
Browse latest Browse all 1764

Including content from XML files in intellisense tooltips

$
0
0

I'm not sure whether this counts as a bug or a feature request, but here goes...

Steps to reproduce

1) Create a project containing a class with the following content

using System;

namespace IntellisenseTest
{
    /// <summary>
    /// Description of Widget.
    /// </summary>
    public class Widget
    {
        /// <summary>
        /// Gets or sets a property which is documented inline.
        /// </summary>
        public string Foo { get; set; }
       
        /// <include file="SharedDocumentation.xml"
        ///          path="doc/members/member[@name='P:IntellisenseTest.Widget.Bar']/*" />
        public string Bar { get; set; }
    }
}

2) Add an XML file to the project called SharedDocumentation.xml with the following content:

<?xml version="1.0"?>
<doc>
    <members>
        <member name="P:IntellisenseTest.Widget.Bar">
            <summary>Gets or sets a property which is documented in a separate XML file.</summary>
        </member>
    </members>
</doc>

3) Hover the mouse pointer over the name of the Bar property in the Widget class until a tooltip appears

Expected result: Tooltip includes the summary text "Gets or sets a property which is documented in a separate XML file"
Actual result: Tooltip only shows the property's signature

If I enable the XML documentation property in the project properties and build a Sandcastle help file, it includes the content from my XML file just as if it were included inline in the code, but it seems that SharpDevelop gets the tooltip content by parsing the source code files rather than from the generated XML documentation file.

I thought I'd have a go at implementing this functionality myself and my investigations led me to the DocumentationUIBuilder class in the ICSharpCode.SharpDevelop project. In the AddDocumentationElement(XmlDocumentationElement) method, there's a switch (element.Name) { ... } block, to which I've added the following:

               case "include":
                    string filename = element.GetAttribute("file");
                    if (string.IsNullOrWhiteSpace(filename))
                    {
                        // file attribute not supplied or is empty, no point trying to read the file
                        break;
                    }
                   
                    // FIXME: this is resolved relative to the SD bin folder, need the project folder
                    string fullyQualifiedFilename = System.IO.Path.GetFullPath(filename);
                    if (System.IO.File.Exists(fullyQualifiedFilename) == false)
                    {
                        AddText("External documentation file '" + fullyQualifiedFilename + "' does not exist");
                        break;
                    }
                   
                    System.Xml.XPath.XPathDocument xdoc = new System.Xml.XPath.XPathDocument(fullyQualifiedFilename);
                    XPathNavigator documentXPathNavigator = xdoc.CreateNavigator();
                    XPathNavigator pathXPathNavigator = documentXPathNavigator.SelectSingleNode(element.GetAttribute("path"));
                    IEntity entity = null; // TODO: what do I set this to?
                    XmlDocumentationElement e = new XmlDocumentationElement(pathXPathNavigator.InnerXml, entity);
                    AddDocumentationElement(e);
                    break;

I know this can be made more robust, e.g. not all the exceptions that could be thrown are handled and it'd probably be tidier to move all of this into a separate method, but for now I have two questions.

1) The tooltip now tells me that the XML file I'm trying to reference can't be found because it's looking in the SharpDevelop bin folder rather than my project folder - how can I get the path to the project folder?
2) In order to pass content from the XML file to the XmlDocumentationElement method, I also need to supply something which implements IEntity - what is this and how do I create it?

Alternatively, am I going about this in completely the wrong way?

SharpDevelop Version : 5.1.0.5134-RC-d5052dc5
.NET Version         : 4.6.01586
OS Version           : Microsoft Windows NT 6.3.9600.0
Current culture      : English (United Kingdom) (en-GB)
Running under WOW6432, processor architecture: x86-64
Working Set Memory   : 161904kb
GC Heap Memory       : 298135kb

Thanks, Simon


Viewing all articles
Browse latest Browse all 1764

Trending Articles