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

[Miguel de Icaza]

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.