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

[Jonathan Pryor]

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