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

[Miguel de Icaza]

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.