Propagate comments to views

Jan 17, 2008 at 10:13 PM
It would be nice if any well-formed XML comments that you've added in the contract would get duplicated by the PipelineBuilder into the view interfaces.
Jan 21, 2008 at 7:54 PM
The PipelineBuilder only examines the contract assembly and doesn't ever look at the actual source code and so it can't actually propegate those comments through. You can, however, use the CommentAttribute to cause comments to be placed on the corresponding types or members on the views.

What are you looking to enable by duplicating those XML comments?
Jan 22, 2008 at 4:24 AM
Edited Jan 22, 2008 at 4:25 AM
I create the contract, and adorn it with XML comments, then I run it through the pipeline builder to automatically generate the adapters and views. The "consumers" of the generated pipeline are the host and addin, which see only the views. I was thinking it would be nice if Intellisense would pick up the interface and method descriptions from XML comments when you hover over the view entities in the client code.

I see that this doesn't work in all contexts, but I can give a specific case where it would. If I add a description to the add-in view interface in the generated add-in-side view:

/// <summary>
/// The add-in view
/// </summary>
System.AddIn.Pipeline.AddInBaseAttribute()
public interface IMyAddIn {
...

I recompile, then open the addin implementation file, where it starts with:

AddIn("My Add-in")
public class MyAddIn : IMyAddIn

If I hover over "IMyAddIn", the tooltip shows:

interface MyAddInViews.IMyAddIn
The add-in view

That's what I had in mind. Since the only code that I write is the contract, it would be nice if I could put these comments into the contract source, and have them propagate out to the generated views.

Thanks,

Allan
Jan 24, 2008 at 3:51 PM
Rather than directly propegating comments from the contract source code, what if there was a PipelineHints attribute that let you specify a summary and parameter information? Are there other XML comments that you would like to express in the views?
Feb 21, 2008 at 3:39 PM
Related to this problem i had made some modifications to the code.

At first i have extended the PipelineHints.CommentAtrribute as following (See "AllowMultiple = true" and "public bool DocComment"):

[Conditional("DEBUG")]
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class | 
AttributeTargets.Interface | AttributeTargets.Property | 
AttributeTargets.Struct, AllowMultiple = true)]
public class CommentAttribute : Attribute
{
    public CommentAttribute(String comment)
    {
        _comment = comment;
    }
 
    public CommentAttribute(String comment, bool docComment)
    {
        _comment = comment;
        _docComment = docComment;
    }
 
    private string _comment;
 
    public string Comment
    {
        get { return _comment; }
        set { _comment = value; }
    }
 
    private bool _docComment;
 
    public bool DocComment
    {
        get { return _docComment; }
        set { _docComment = value; }
    }
}

So you can declare comments like this:
[PipelineHints.Comment("<remarks>Any remarks...</remarks>", DocComment = true)]
[PipelineHints.Comment("<summary>The view of the add-in contract.</summary>", DocComment = true)]
[PipelineHints.Comment("=======================", DocComment = false)]
[AddInContract]
public interface IServiceAddIn : IContract
{
...

which results in an add-in view code like this:
// =======================
/// <summary>The view of the add-in contract.</summary>
/// <remarks>Any remarks...</remarks>
[System.AddIn.Pipeline.AddInBaseAttribute()]
public interface IServiceAddIn
{
...

and a documentation xml like these:
<doc>
    <assembly>
        <name>AddIn.View</name>
    </assembly>
    <members>
        <member name="T:AddIn.IServiceAddIn">
            <remarks>Any remarks...</remarks>
            <summary>The view of the add-in contract.</summary>
        </member>
    </members>
...
</doc>

Now you can use multiple instances of the PipelineHints.CommentAtrribute but the bad news are, that the resulting comments not ever have the correct order.
To make these changes workable you also have to make some changes in the PipelineBuilder.cs:
Modify all lines which includes "new CodeCommentStatement(comment.Comment)" to "new CodeCommentStatement(comment.Comment, comment.DocComment)".


A question at the end: Could this be included in the next version? :-)

Thanks,
Marco
Mar 28, 2008 at 10:45 AM
Personally, I'd prefer a pipeline attribute that allows you to specify doc include information in your contract. Something like:
[DocInclude("../SomeContractDoc.xml", Path="/some/path")]
public interface ISomeContract : IContract
{
}
This would be translated to (in the generated view):
/// <include file='../SomeContractDoc.xml' path='/some/path'/>
public interface ISome
{
}
This would allow be to maintain the documentation in a more soluble format, reduces the verbosity of the contract and the generated view.

Regards,
Kent