Exception when using monodocer on System.Windows.Forms.dll

Hello,

since no one on the winforms list replied to my mail I
thought maybe the docs 
guys know something about it.

Kind Regards,
Valentin S.

----------  Forwarded Message  ----------

Subject: [Mono-winforms-list] Exception when using monodocer
on 
System.Windows.Forms.dll
Date: Sunday 10 December 2006 09:05
From: latency <latencygmx.de>
To: mono-winforms-listlists.ximian.com

Hi all,

as I'm working pretty much with the System.Windows.Forms
namespace I thought
it would be great to have it's documentation in the mondoc
browser.

So I tried to run monodocer and generate the documentation
but monodcer fails
and displays the following exception.

Updating: System.Windows.Forms.TextBox
System.NullReferenceException: Object reference not set to
an instance of an
object
  at CSharpFullMemberFormatter.AppendVisibility
(System.Text.StringBuilder
buf, System.Reflection.MethodBase method) [0x00000]
  at CSharpFullMemberFormatter.GetEventDeclaration
(System.Reflection.EventInfo e) [0x00000]
  at MemberFormatter.GetDeclaration
(System.Reflection.MemberInfo member)
[0x00000]
  at Stub.MakeMemberSignature (System.Reflection.MemberInfo
mi) [0x00000]
  at Stub.MakeMember (System.Xml.XmlDocument doc,
 System.Reflection.MemberInfo mi) [0x00000]
  at Stub.UpdateType (System.Xml.XmlElement root,
System.Type type, Boolean
addmembers) [0x00000]
  at Stub.StubType (System.Type type) [0x00000]
  at Stub.DoUpdateAssembly (System.Reflection.Assembly
assembly,
System.Xml.XmlElement index_types, System.String source,
System.String dest,
System.Collections.Hashtable goodfiles) [0x00000]
  at Stub.DoUpdateAssemblies (System.String source,
System.String dest)
[0x00000]
  at Stub.Main (System.String[] args) [0x00000]
Members Added: 0, Members Deleted: 0

Can somebody tell me what went wrong? I'm running Mono
1.2.2.1 and used the
Winforms assembly in /usr/lib/mono/2.0/ .

Thanks in advance,
Valentin S.
_______________________________________________
Mono-winforms-list maillist  -  Mono-winforms-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-winform
s-list

-------------------------------------------------------
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Thu, 2006-12-14 at 19:13 +0100, latency wrote:
> as I'm working pretty much with the
System.Windows.Forms namespace I thought
> it would be great to have it's documentation in the
mondoc browser.
> 
> So I tried to run monodocer and generate the
documentation but monodcer fails
> and displays the following exception.
> 
> Updating: System.Windows.Forms.TextBox
> System.NullReferenceException: Object reference not set
to an instance of an
> object
>   at CSharpFullMemberFormatter.AppendVisibility
(System.Text.StringBuilder
> buf, System.Reflection.MethodBase method) [0x00000]

You might try using monodocer from svn-HEAD.  There was a
change on
2006-12-07 to AppendVisibility() which should avoid the
NullReferenceException.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hello,

thanks for the advice it worked well. But there's still one
problem.
I've managed to integrate the System.Windows.Forms
documentation into Mondoc 
but this included changing the makefile in the monodoc/class
folder and 
adding the System.Windows.Forms Doc into the class folder of
mondoc.

The change of the makefile is not very much and I attached
it to the email but 
for uploading the docs of SWF by monodocer, well that I
can't do since I've 
got no access to the server and I'm not familiar wether this
is the right 
thing to do.

However I would still like to see SWF in my monodoc browser
so can somebody 
tell me how this can be accomplished without having to hack
monodoc after 
each update.

Kind Regards,
Valentin S.

On Friday 15 December 2006 01:52, you wrote:
> On Thu, 2006-12-14 at 19:13 +0100, latency wrote:
> > as I'm working pretty much with the
System.Windows.Forms namespace I
> > thought it would be great to have it's
documentation in the mondoc
> > browser.
> >
> > So I tried to run monodocer and generate the
documentation but monodcer
> > fails and displays the following exception.
> >
> > Updating: System.Windows.Forms.TextBox
> > System.NullReferenceException: Object reference
not set to an instance of
> > an object
> >   at CSharpFullMemberFormatter.AppendVisibility
> > (System.Text.StringBuilder buf,
System.Reflection.MethodBase method)
> > [0x00000]
>
> You might try using monodocer from svn-HEAD.  There was
a change on
> 2006-12-07 to AppendVisibility() which should avoid the
> NullReferenceException.
>
>  - Jon
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sat, 2006-12-16 at 15:30 +0100, latency wrote:
> thanks for the advice it worked well. But there's still
one problem.
> I've managed to integrate the System.Windows.Forms
documentation into Mondoc 
> but this included changing the makefile in the
monodoc/class folder and 
> adding the System.Windows.Forms Doc into the class
folder of mondoc.
> 
> The change of the makefile is not very much and I
attached it to the email but 
> for uploading the docs of SWF by monodocer, well that I
can't do since I've 
> got no access to the server and I'm not familiar wether
this is the right 
> thing to do.
> 
> However I would still like to see SWF in my monodoc
browser so can somebody 
> tell me how this can be accomplished without having to
hack monodoc after 
> each update.

Use the `msassembler' command and install the documentation
separately.

http://www.mono
-project.com/Assembler has more information.

You can do this by creating a `swf-docs.source' file with
the contents:

	<?xml version="1.0"?>
	<monodoc>
	  <source provider="ecma"
basefile="netdocs" path="classlib"/>
	</monodoc>

Then create swf-docs.tree and swf-docs.zip files with:

	mdassembler --ecma System.Windows.Forms/en -o swf-docs

where System.Windows.Forms/en is the directory containing
the
monodocer-generated documentation.

Then install this documentation with:

	cp swf-docs.source swf-docs.tree swf-docs.zip 
		`monodoc --get-sourcesdir`

Close and restart monodoc to view this documentation.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hi,

as I said, I've managed to include the SWF documentation
into monodoc. But 
that would be a solution which is only available to me. But
my intention was 
it to find a way where SWF documentation would be shipped
with monodoc 
automatically. (Maybe I did not express myself clear enough
in the last 
mail.)

The only way I can think of right now is adding the swf docs
to the build 
process of monodoc. But I don't know if this is possible and
how this will 
work with user contributions and so on since I'm not to
familiar with the 
whole thing.

Btw. I'm aware of the Assembler page in the wiki, I
"wrote" it yesterday. But 
could you please tell me where is the difference between
mdassembler and 
assembler?

Kind Regards,
Valentin S.

On Sunday 17 December 2006 03:43, you wrote:
> On Sat, 2006-12-16 at 15:30 +0100, latency wrote:
> > thanks for the advice it worked well. But there's
still one problem.
> > I've managed to integrate the System.Windows.Forms
documentation into
> > Mondoc but this included changing the makefile in
the monodoc/class
> > folder and adding the System.Windows.Forms Doc
into the class folder of
> > mondoc.
> >
> > The change of the makefile is not very much and I
attached it to the
> > email but for uploading the docs of SWF by
monodocer, well that I can't
> > do since I've got no access to the server and I'm
not familiar wether
> > this is the right thing to do.
> >
> > However I would still like to see SWF in my
monodoc browser so can
> > somebody tell me how this can be accomplished
without having to hack
> > monodoc after each update.
>
> Use the `msassembler' command and install the
documentation separately.
>
> http://www.mono
-project.com/Assembler has more information.
>
> You can do this by creating a `swf-docs.source' file
with the contents:
>
> 	<?xml version="1.0"?>
> 	<monodoc>
> 	  <source provider="ecma"
basefile="netdocs" path="classlib"/>
> 	</monodoc>
>
> Then create swf-docs.tree and swf-docs.zip files with:
>
> 	mdassembler --ecma System.Windows.Forms/en -o swf-docs
>
> where System.Windows.Forms/en is the directory
containing the
> monodocer-generated documentation.
>
> Then install this documentation with:
>
> 	cp swf-docs.source swf-docs.tree swf-docs.zip 
> 		`monodoc --get-sourcesdir`
>
> Close and restart monodoc to view this documentation.
>
>  - Jon
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sun, 2006-12-17 at 09:50 +0100, latency wrote:
> as I said, I've managed to include the SWF
documentation into monodoc. But 
> that would be a solution which is only available to me.
But my intention was 
> it to find a way where SWF documentation would be
shipped with monodoc 
> automatically. (Maybe I did not express myself clear
enough in the last 
> mail.)

If you have an svn account, you can add the files at any
time.
Otherwise, you need to wait until one of us has a chance to
update svn.

This also requires updating the monodoc build process. 
Currently it
uses monodoc/generator/updater.exe, while it needs to use
monodocer/tools/monodocer.exe, as monodocer.exe supports
generics while
updater.exe doesn't.

This change is trivial.

What is less trivial is that we want to separate the .NET
1.1 docs from
the .NET 2.0 docs.

This is also trivial -- add ``-since:".NET 2.0"''
to the monodocer
command line, and any added types/members will get a
<since/> element
added with the specified value.  If we assume that the
previous docs
only contain 1.1 docs (and *all* of the 1.1 docs), then this
works
fairly well.

This could all be done now, actually, but I had been holding
off on
doing it as I wanted to change monodocer so that it could
import the
ECMA 335 documentation, as ECMA 3rd Edition (and now 4th
Edition)
contains documentation for many of the generic
types/members, and we'd
like to make use of this.

However, as per discussion with miguel earlier last week, we
currently
plan to always overwrite the existing docs with the new docs
when
importing ECMA docs, so there is no reason to wait on
updating the
monodoc/class docs for this new support.

Given this, I'll try to get updated docs committed to svn
some time this
week, and work on the monodocer support later.

> The only way I can think of right now is adding the swf
docs to the build 
> process of monodoc. But I don't know if this is
possible and how this will 
> work with user contributions and so on since I'm not to
familiar with the 
> whole thing.

This is correct, SWF would need to be added to the build
process of
monodoc.  We really should make sure that all assemblies
included with
mono are part of monodoc as well.

> Btw. I'm aware of the Assembler page in the wiki, I
"wrote" it yesterday. But 
> could you please tell me where is the difference
between mdassembler and 
> assembler?

mdassembler is a script which executes assembler.exe:

	#!/bin/sh

	prefix=/usr
	exec_prefix=$
	monodocdir=/usr/lib/monodoc

	exec /usr/bin/mono $monodocdir/assembler.exe "$"

So it's easier for everyone to use.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sunday 17 December 2006 14:54, you wrote:
> If you have an svn account, you can add the files at
any time.
> Otherwise, you need to wait until one of us has a
chance to update svn.

No I don't have one. So I just pull some Tea and wait for
the changes to 
happen.


> This also requires updating the monodoc build process. 
Currently it
> uses monodoc/generator/updater.exe, while it needs to
use
> monodocer/tools/monodocer.exe, as monodocer.exe
supports generics while
> updater.exe doesn't.
>
> This change is trivial.
>
> What is less trivial is that we want to separate the
.NET 1.1 docs from
> the .NET 2.0 docs.
>
> This is also trivial -- add ``-since:".NET
2.0"'' to the monodocer
> command line, and any added types/members will get a
<since/> element
> added with the specified value.  If we assume that the
previous docs
> only contain 1.1 docs (and *all* of the 1.1 docs), then
this works
> fairly well.
>
> This could all be done now, actually, but I had been
holding off on
> doing it as I wanted to change monodocer so that it
could import the
> ECMA 335 documentation, as ECMA 3rd Edition (and now
4th Edition)
> contains documentation for many of the generic
types/members, and we'd
> like to make use of this.
>
> However, as per discussion with miguel earlier last
week, we currently
> plan to always overwrite the existing docs with the new
docs when
> importing ECMA docs, so there is no reason to wait on
updating the
> monodoc/class docs for this new support.
>
> Given this, I'll try to get updated docs committed to
svn some time this
> week, and work on the monodocer support later.

Is the current documentation, including all user
contributions for the 1.1 or 
2.0 version of the framework? Will the current contributions
survive the 
change of the build process?

And in I my opinion this concept should be extended to meet
the version 
changes of third-party assemblies that are shipped with mono
as well. Because 
if we only distinguish between .Net 1.1 and 2.0 third-party
assemblies can 
not be documented in a way where users see in which version
of the assembly 
the api has been changed.


> This is correct, SWF would need to be added to the
build process of
> monodoc.  We really should make sure that all
assemblies included with
> mono are part of monodoc as well.

I've taken a look into it and this should be the list of
assemblies to add:
(These are all assemblies that I've found in the GAC of a
newly compiled mono 
which are not present in monodoc. But I guess the assemblies
still under 
development like System.Transactions can be removed from the
list.)

- Accessability
- CustomMarshalers
- FireBird
- l18n
- IBM.Data.DB2
- SharpZipLib
- Microsoft.Build.*
- Mono.C5
- Mono.Data.* (currently only SqlClient is included)
- Mono.Http
- OpenSystem.C
- PEAPI
- System.Design
- System.EnterpriseServices
- System.Management
- System.Messeging
- System.ServiceProcess
- System.Transaction


> mdassembler is a script which executes assembler.exe:
>
> 	#!/bin/sh
>
> 	prefix=/usr
> 	exec_prefix=$
> 	monodocdir=/usr/lib/monodoc
>
> 	exec /usr/bin/mono $monodocdir/assembler.exe
"$"
>
> So it's easier for everyone to use.

I've found that out by myself 5 minutes after I sent the
mail. But still 
thanks for the answer 

Kind Regards,
Valentin S.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hello,

> Is the current documentation, including all user
contributions for the 1.1 or 
> 2.0 version of the framework? Will the current
contributions survive the 
> change of the build process?

Most stuff is for 1.0, with a handful of exceptions (down to
a handful
of classes that we had to document).

In my opinion, the best thing to do would be to:

	* Add 1.0 docs.

	* Wait for 2.0 to be API complete.

	* Re-run the appropriate tool to add the 2.0 deltas and
	  inserting the "Since 2.0" messages.
	 
> And in I my opinion this concept should be extended to
meet the version 
> changes of third-party assemblies that are shipped with
mono as well. Because 
> if we only distinguish between .Net 1.1 and 2.0
third-party assemblies can 
> not be documented in a way where users see in which
version of the assembly 
> the api has been changed.

The tag for "since" allows any string to be
inserted.

> I've taken a look into it and this should be the list
of assemblies to add:
> (These are all assemblies that I've found in the GAC of
a newly compiled mono 
> which are not present in monodoc. But I guess the
assemblies still under 
> development like System.Transactions can be removed
from the list.)

My concerns about adding more docs fall in the following
categories:

	* The assembly is a third-party assembly, and should be
	  documented "upstream" before we do any
integration.

	  The "upstream" documentation could probably be
inline docs 
	  (C5, FireBird, SharpZipLib) or it could be open to new
docs,
	  in that case, we can revisit this decision.

	* Internal assemblies should not be documented (Custom
	  Marshallers, I18N. OpenSystem.C).   

	  Things like PEAPI should be considered
	  internal, as there are two replacements for it that are
being
	  maintained (Cecil and PERWAPI) and those should be
	  documented. 

	* The same applies to assemblies that are merely stubs to
get
	  things to compile, as technically they do not provide any
	  functionality (Sys.Messaging, Sys.EnterpriseServices,
	  Accessibility).

	* Under development of incomplete libraries should not be
	  documented, and this includes the Mono.Data assembly (not
	  to be confused with Mono.Data.SqliteClient,Sybase).

	* Libraries that are not API-complete (re-implementations)
	  pose a challenge for the monodoc updater, so I rather not
	  waste time on those yet (Microsoft.Build.* and all of the
	  Olive class libraries)

Which leaves us with the following ones to document:

> - Mono.Data.* (currently only SqlClient is included)

Only the concrete Mono.Data.*

> - Mono.Http
> - System.ServiceProcess
> - System.Transaction

And finally, my last concern is that stubs are not
documentation,
stubbing things out is the easy part.  Actually writing the
documentation is the hard part, and we have historically not
been able
to attract people to do this work.

Miguel.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sun, 2006-12-17 at 13:19 -0500, Miguel de Icaza wrote:
> In my opinion, the best thing to do would be to:
> 
> 	* Add 1.0 docs.

Simple enough.

> 	* Wait for 2.0 to be API complete.

Implies waiting a few years for all 2.0 types/methods to be
stubbed out.

> 	* Re-run the appropriate tool to add the 2.0 deltas
and
> 	  inserting the "Since 2.0" messages.

Simple enough.

Obviously, I have issues with "waiting for 2.0 to be
API complete."  I
also don't see the point in waiting, since the only
differences between
1.0 and 2.0 assemblies is (a) the assembly we run against,
and (b)
whether we use a -since argument.

Thus, I propose the following: Change
monodoc/class/Makefile.am's
`update' target to be:

	update:
		for a in $(UPDATE_ASSEMBLIES); do 
			mono --debug ../tools/monodocer.exe 
			../../mcs/class/default/$a ;
		done
		for a in $(UPDATE_ASSEMBLIES); do 
			mono --debug ../tools/monodocer.exe 
			../../mcs/class/net_2_0/$a ;
		done

That is, when updating run monodocer.exe *twice*, once
against the 1.0
assembly, and once against the 2.0 assembly.

This makes the assumption that when a member is added it's
added to the
appropriate versions (e.g. if it's a 1.1 member we're adding
it's also
added to the 2.0 profile as well), which is a fairly sane
assumption.

The only downside is that this doubles runtime, but
historically it
isn't run that often, so this shouldn't be a problem either.

The major advantage to this is that we don't need to finish
stubbing out
2.0 types/members before we can start generating the
documentation for
those members.  Even if we don't have any detailed
documentation, it's
still useful to have the stubs, if only to see what types
& members
exist, view the argument list, get argument names, etc.
	 
> My concerns about adding more docs fall in the
following categories:
> 
> 	* The assembly is a third-party assembly, and should
be
> 	  documented "upstream" before we do any
integration.
> 
> 	  The "upstream" documentation could
probably be inline docs 
> 	  (C5, FireBird, SharpZipLib) or it could be open to
new docs,
> 	  in that case, we can revisit this decision.

We can easily handle inline docs if upstream ever starts
using them,
with `monodocer -importslashdoc'.

> 	* Under development of incomplete libraries should not
be
> 	  documented, and this includes the Mono.Data assembly
(not
> 	  to be confused with Mono.Data.SqliteClient,Sybase).

Why?

> 	* Libraries that are not API-complete
(re-implementations)
> 	  pose a challenge for the monodoc updater, so I
rather not
> 	  waste time on those yet (Microsoft.Build.* and all
of the
> 	  Olive class libraries)

I proposed a solution to this above.  If it's a 2.0
assembly, we don't
need to run the updater twice either, as any/all added
members should
get the <since/> element inserted.

> And finally, my last concern is that stubs are not
documentation,
> stubbing things out is the easy part.  Actually writing
the
> documentation is the hard part, and we have
historically not been able
> to attract people to do this work.

Stubs may be the easy part, but don't underestimate their
usefulness.
Wondering if a member is supported?  It's a lot easier to
say "is it in
monodoc" than to say "check the source." 
(Granted, this won't work for
NotImplementedExceptions, but those are supposed to be a
rarity, with
the stated policy that unimplemented members shouldn't be
implemented at
all, precisely so that mcs can warn about unimplemented
functionality.)

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hello,

> The major advantage to this is that we don't need to
finish stubbing out
> 2.0 types/members before we can start generating the
documentation for
> those members.  Even if we don't have any detailed
documentation, it's

And this is the key "start generating
documentation".   It is just *not*
happening. 

If we have not got much traction with people documenting
1.0, how are we
going to get more contributions to 2.0?

> > 	* Under development of incomplete libraries
should not be
> > 	  documented, and this includes the Mono.Data
assembly (not
> > 	  to be confused with
Mono.Data.SqliteClient,Sybase).
> 
> Why?

Because it is a waste of time.

Until a library is used by a number of consumers the API is
not
guaranteed to be stable, or well designed.  Documenting APIs
that are in
flux is mostly a waste of time.

Considering that we have *stable* APIs that are
undocumented,
documenting unstable ones makes no sense.   

> > And finally, my last concern is that stubs are not
documentation,
> > stubbing things out is the easy part.  Actually
writing the
> > documentation is the hard part, and we have
historically not been able
> > to attract people to do this work.
> 
> Stubs may be the easy part, but don't underestimate
their usefulness.
> Wondering if a member is supported?  It's a lot easier
to say "is it in
> monodoc" than to say "check the source."
 (Granted, this won't work for
> NotImplementedExceptions, but those are supposed to be
a rarity, with
> the stated policy that unimplemented members shouldn't
be implemented at
> all, precisely so that mcs can warn about unimplemented
functionality.)

My major objection to the 2.0 support is that someone needs
to make sure
that this actually works.

Miguel.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sunday 17 December 2006 21:19, Jonathan Pryor wrote:
On Sun, 2006-12-17 at 13:19 -0500, Miguel de Icaza wrote:

> Thus, I propose the following: Change
monodoc/class/Makefile.am's
> `update' target to be:
>
> 	update:
> 		for a in $(UPDATE_ASSEMBLIES); do 
> 			mono --debug ../tools/monodocer.exe 
> 			../../mcs/class/default/$a ;
> 		done
> 		for a in $(UPDATE_ASSEMBLIES); do 
> 			mono --debug ../tools/monodocer.exe 
> 			../../mcs/class/net_2_0/$a ;
> 		done

Please don't forget to adapt the makefile to assemble the
generated 
documentation. Right now this is not being done in a generic
way, every 
documented assembly is hard coded into the Makefile.am.

> And finally, my last concern is that stubs are not
documentation,
> stubbing things out is the easy part.  Actually writing
the
> documentation is the hard part, and we have
historically not been able
> to attract people to do this work.

This may be right but not providing the stubs in monodoc
makes it impossible 
for users to contribute documentation. That way at least a
few things can be 
documented. In addition I have to say that I agree to
Jonathan stubs can be 
usefull to since they provide the name of the argument, from
which you can at 
least imagine how to use the method correctly.

Kind Regards,
Valentin S.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

> Thus, I propose the following: Change
monodoc/class/Makefile.am's
> `update' target to be:
> 
> 	update:
> 		for a in $(UPDATE_ASSEMBLIES); do 
> 			mono --debug ../tools/monodocer.exe 
> 			../../mcs/class/default/$a ;
> 		done
> 		for a in $(UPDATE_ASSEMBLIES); do 
> 			mono --debug ../tools/monodocer.exe 
> 			../../mcs/class/net_2_0/$a ;
> 		done
> 
> That is, when updating run monodocer.exe *twice*, once
against the 1.0
> assembly, and once against the 2.0 assembly.
> 
> This makes the assumption that when a member is added
it's added to the
> appropriate versions (e.g. if it's a 1.1 member we're
adding it's also
> added to the 2.0 profile as well), which is a fairly
sane assumption.

Agreed.  This looks sane.

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?

Miguel.

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

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&qu
ot; />

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


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hello,

> 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:

I guess it might work.

> 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&qu
ot; />

That would do it.

> 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).

Have you tried sending a SIGQUIT to the process?  These days
it dumps a
nice stack trace of where things are stuck.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hello,

> Please don't forget to adapt the makefile to assemble
the generated 
> documentation. Right now this is not being done in a
generic way, every 
> documented assembly is hard coded into the Makefile.am.

Am not sure I understand the problem.

> This may be right but not providing the stubs in
monodoc makes it impossible 
> for users to contribute documentation. That way at
least a few things can be 
> documented. In addition I have to say that I agree to
Jonathan stubs can be 
> usefull to since they provide the name of the argument,
from which you can at 
> least imagine how to use the method correctly.

There is something else that we need to keep in mind: it
turns out that
argument names in the ECMA spec are relevant.  They are not
purely for
decorative purposes.

This is a problem, because early on, we did not use the same
arguments
as Microsoft did, so we will have to go back and fix that at
some point.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Hi,

On Wednesday 20 December 2006 20:21, you wrote:
> Hello,
>
> > Please don't forget to adapt the makefile to
assemble the generated
> > documentation. Right now this is not being done in
a generic way, every
> > documented assembly is hard coded into the
Makefile.am.
>
> Am not sure I understand the problem.

I thought of the following lines in the Makefile.am:

mono --debug $(ASSEMBLER) --ecma $(srcdir)/corlib/en/ --ecma

$(srcdir)/System/en/  --ecma $(srcdir)/System.XML/en/ ...

This is where the assembler is being called, and as you can
see all the 
assemblies that are being used have been added to the
makefile by hand. So if 
we add more assemblies to monodoc we must also take care to
add them here as 
well otherwise they won't make it into monodoc.

> There is something else that we need to keep in mind:
it turns out that
> argument names in the ECMA spec are relevant.  They are
not purely for
> decorative purposes.
>
> This is a problem, because early on, we did not use the
same arguments
> as Microsoft did, so we will have to go back and fix
that at some point.

Could corecompare be extended to compare argument names as
well? Otherwise it 
would be quite fun and time intensive to look at each
argument name and 
compare them to the MS names.

Kind Regards,
Valentin S.
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list