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

Miguel de Icaza miguel at ximian.com
Sun Dec 17 16:15:46 EST 2006


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

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.


More information about the Mono-docs-list mailing list