Ref. overloaded method in XML comments

30 Oct 2007 8:06 PM

Paul S

Hi

In a class InfoCollection I have 2 overloads:

        public virtual DataSet Update()
        public virtual DataSet Update(UpdateType ut)

that I reference in the documentaion on another method

        /// <summary>
        /// Delete this object and removes it from the collection. Call
        /// <see cref="InfoCollection.Update"/> to delete it from the
database.
        /// </summary>

however I get this warning:

cref attribute 'InfoCollection.Update()' that could not be resolved

How do I reference an overloaded method ?

--
Thanks
Paul S

31 Oct 2007 5:32 AM

Walter Wang [MSFT]

Hi Paul,

This is because you haven't used parenthesis and the parameter type. If you
need to reference the first overloaded (without parameters), just use

<see cref="InfoCollection.Update()" />

If you need to use the second overloaded version with one parameter type
UpdateType, just use

<see cref="InfoCollection.Update(UpdateType)" />

Hope this helps.

Regards,
Walter Wang (waw***@online.microsoft.com, remove 'online.')
Microsoft Online Community Support

==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================

This posting is provided "AS IS" with no warranties, and confers no rights.

31 Oct 2007 9:16 AM

Paul S

Hi Walter

Your answer made me try - again - to do what you suggested without luck. I
think the problem is the the Update method is an abstract method in a base
class - sorry that wasn't in the original question

--
Regards
Paul S

""Walter Wang [MSFT]"" wrote:

Show quote

> Hi Paul,
>
> This is because you haven't used parenthesis and the parameter type. If you
> need to reference the first overloaded (without parameters), just use
>
> <see cref="InfoCollection.Update()" />
>
> If you need to use the second overloaded version with one parameter type
> UpdateType, just use
>
> <see cref="InfoCollection.Update(UpdateType)" />
>
>
> Hope this helps.
>
>
> Regards,
> Walter Wang (waw***@online.microsoft.com, remove 'online.')
> Microsoft Online Community Support
>
> ==================================================
> When responding to posts, please "Reply to Group" via your newsreader so
> that others may learn and benefit from your issue.
> ==================================================
>
> This posting is provided "AS IS" with no warranties, and confers no rights.
>
>
>

31 Oct 2007 9:55 AM

Walter Wang [MSFT]

Hi Paul,

I just tried following code:

/// <summary>
/// <see cref="Foo.Bar()" />
/// <see cref="Foo.Bar(int)" />
/// </summary>
public abstract class Foo
{
    /// <summary>
    /// </summary>
    public abstract void Bar();
    /// <summary>
    /// </summary>
    public abstract void Bar(int x);
}

/// <summary>
/// <see cref="Child.Bar()" />
/// <see cref="Child.Bar(int)" />
/// </summary>
public class Child : Foo
{
    /// <summary>
    /// </summary>
    public override void Bar()
    {
    }

    /// <summary>
    /// </summary>
    public override void Bar(int x)
    {
    }
}

csc /target:library /doc:foo.xml foo.cs

and it didn't generate any warnings or errors.

Would you please create a reproducible project and send it to me? Thanks.

Regards,
Walter Wang (waw***@online.microsoft.com, remove 'online.')
Microsoft Online Community Support

==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================

This posting is provided "AS IS" with no warranties, and confers no rights.

31 Oct 2007 9:56 AM

Walter Wang [MSFT]

By the way, I'm using Visual Studio 2005.

5 Nov 2007 11:48 AM

Paul S

Hi Walter
My project is in VB but I don't see that that should make a difference. I
think I need to boil my project down to a small example.

--
Paul S

""Walter Wang [MSFT]"" wrote:

Show quote

> By the way, I'm using Visual Studio 2005.
>
>
>
>

7 Nov 2007 6:05 AM

Walter Wang [MSFT]

Hi Paul,

This looks like an issue of VB.NET compiler that currently didn't expand
the method in "cref" attribute:

#VB.NET 2005 / Sandcastle treatment of <see cref=""/> - MSDN Forums
http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=802863&SiteID=1

#Feedback: VB 2005 (SP1 Beta 1) code comments: Link tag attribute not
converted from relative to full path by compiler.
http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?Feedbac
kID=219950

If you manually specify a full expanded method reference, then VB.NET will
not issue the warning:

''' <summary>
''' <see cref="Foo.Bar" />
''' <see cref="M:Foo.Bar(System.Int32)" />
''' </summary>
Public MustInherit Class Foo
Public MustOverride Sub Bar()
Public MustOverride Sub Bar(ByVal x As Integer)
End Class

We're sorry for the inconvenience.

Regards,
Walter Wang (waw***@online.microsoft.com, remove 'online.')
Microsoft Online Community Support

==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================

This posting is provided "AS IS" with no warranties, and confers no rights.

7 Nov 2007 9:10 AM

Paul S

That solved the problem - thanks a lot Walter

--
Regards
Paul S

""Walter Wang [MSFT]"" wrote:

Show quote

> Hi Paul,
>
> This looks like an issue of VB.NET compiler that currently didn't expand
> the method in "cref" attribute:
>
> #VB.NET 2005 / Sandcastle treatment of <see cref=""/> - MSDN Forums
> http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=802863&SiteID=1
>
> #Feedback: VB 2005 (SP1 Beta 1) code comments: Link tag attribute not
> converted from relative to full path by compiler.
> http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?Feedbac
> kID=219950
>
>
> If you manually specify a full expanded method reference, then VB.NET will
> not issue the warning:
>
> ''' <summary>
> ''' <see cref="Foo.Bar" />
> ''' <see cref="M:Foo.Bar(System.Int32)" />
> ''' </summary>
> Public MustInherit Class Foo
> Public MustOverride Sub Bar()
> Public MustOverride Sub Bar(ByVal x As Integer)
> End Class
>
>
> We're sorry for the inconvenience.
>
>
> Regards,
> Walter Wang (waw***@online.microsoft.com, remove 'online.')
> Microsoft Online Community Support
>
> ==================================================
> When responding to posts, please "Reply to Group" via your newsreader so
> that others may learn and benefit from your issue.
> ==================================================
>
> This posting is provided "AS IS" with no warranties, and confers no rights.
>
>