Bug generating Events docs with VB.Net

May 10, 2008 at 3:32 AM
        ''' <summary>
        ''' Evento disparado quando a sessão é reiniciada
        ''' </summary>
        ''' <param name="session">Sessão sendo reiniciada</param>
        Public Event SessionReseted(ByVal session As Session)

In VisualBasic, there is an implicit declaration of a delegate named SessionResetedEventHandler, and we can not declare this delegate by hand. For VB users, this delegate is invisible, 'cos we don't need it (VB uses AddHandler SessionReseted, FunctionPointer and RaiseEvent Event(Arguments))

But, SandCastle inserts the SessionResetedEventHandler without any documentation.

The expected behavior is a XML comment "inheritance" that would document the EventHandler with the same xml comments from its parent event.

To reproduce:

Create a project in VB with the following:

Namespace nsTest
  Public Class clsTest

    Public Event evTest(ByRef argTest As Integer)

    Rem Public Delegate Sub evTestEventHandler(ByRef argTest As Integer) <--- This is forbidden, because there is already an implicit delegate in this class, so, we cannot document it

    Public Sub TestEvent()
        Dim X As Integer = 3

        RaiseEvent evTest(X)
    End Sub
End Class

The sandcastle will generate the implicit delegate evTestEventHandler, but without any documentation.
May 10, 2008 at 5:33 AM

Unless there's some way to identify the delegate as being implicitly declared by VB.NET via reflection, such as by searching for a particular Attribute that the compiler adds to the delegate, it's unlikely that this will be something that Sandcastle can handle with its current tool set (which uses reflection).  In other languages the delegate is not implicit, so automatically inheriting documentation might not be desirable.

One option is to add the XML documentation manually before it's supplied to Sandcastle, or create a tool that can parse the XML documentation and add automatically inherit comments for event delegates.  Eric Woodruff wrote a tool that inherits documentation for other APIs, so maybe this is a feature that's worth adding to that tool.

- Dave
May 11, 2008 at 2:03 AM

It's not a bug.  The delegate is compiler generated but since it's public and not marked with a CompilerGenerated attribute, it gets included in the reflection information.  I'm not sure commenting it with the same comments as the event is a good idea anyway since a delegate is not an event and the comments may not be a good fit.  If it doesn't really add anything to the documentation and you don't use it anyway, you could just get rid of it with the API filter.  The other option is to redo the event so that it conforms to the standard way of doing it which is to use EventArgs or a derived EventArgs class and use EventHandler or EventHandler<T>.  That would also get rid of the compiler generated delegate.