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-list@lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
