[Mono-docs-list] Fwd: [Mono-winforms-list] Exception when using monodocer on System.Windows.Forms.dll

[Jonathan Pryor]

On Mon, 2006-12-18 at 16:35 -0500, Miguel de Icaza wrote:
> We have discovered something in Moma that is probably important to look
> into.   
> 
> In 2.0, a number of new overrides were done, for example, consider
> Windows.Forms' Button override for OnMouseEnter:
> 
>            protected override void OnMouseEnter (EventArgs e)
> 
> This method which was introduced in 2.0 matter only from the
> compiler/reflection standpoint (ie, you generate a reference to
> Button.OnMouseEnter instead of Control.OnMouseEnter which is where the
> method was originally defined).
> 
> The issue here is how to properly flag a method as being a 2.0 feature
> or not.    Because *source code wise* (and this is what Monodoc should
> document, and this is how MSDN documents it) the source code is
> compatible since OnMouseEnter existed in the 1.1 profile.
> 
> So now the question is: how do we implement this feature?

Add `-overrides' to the monodocer command line. :-)

-overrides will add members which are overridden into the XML file; for
example, System.Windows.Forms/en/System.Windows.Forms/Button.xml would
have:

    <Member MemberName="OnMouseLeave">
      <MemberSignature Language="C#" Value="protected override void
OnMouseLeave (System.EventArgs e);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="e" Type="System.EventArgs" />
      </Parameters>
      <Docs>
        <param name="e">To be added.</param>
        <summary>To be added.</summary>
        <remarks>To be added.</remarks>
        <since version=".NET 2.0" />
      </Docs>
    </Member>

Note (1) the <MemberSignature/> includes `override', and (2) there is a
<since/> element noting that this member was added in .NET 2.0.

The only thing missing is that <summary/> and <remarks/> should have
pre-canned text:

	This member overrides <see 
	  cref="T:System.Windows.Forms.ButtonBase.OnMouseEnter" />

and it should be fairly easy to implement that support.

Does this suffice?

The only remaining problem is that monodocer occasionally hangs when
processing an assembly.  I'm still looking into this (and wondering how
many chickens I need to sacrifice in order for mdb to actually work).

 - Jon