[Mono-docs-list] Documentation Updating...

[Jonathan Pryor]

I'm working on getting monodocer support into monodoc/class.  As
suggested in an earlier email, my current approach is this:

UPDATE_COMMAND = \
	mono --debug ../tools/monodocer1.exe -pretty -overrides -ignore_extra_docs  \
		-assembly:@prefix@/lib/mono/1.0/$(1).dll                            \
		-path:./$(2)/en || exit 1;                                          \
	mono --debug ../tools/monodocer.exe -pretty -overrides                      \
		-assembly:@prefix@/lib/mono/2.0/$(1).dll                            \
		-path:./$(2)/en || exit 1;

update:
	for i in $(UPDATE_DIRS); do \
		a=`echo $$i | sed -r 's/^([^:]+).*$$/\1/'`; \
		d=`echo $$i | sed -r 's/^[^:]+:(.*)$$/\1/'`; \
		if test -z "$$d" ; then d="$$a"; fi; \
		$(call UPDATE_COMMAND,$$a,$$d)
	done
	mono --debug ../tools/monodocer.exe -pretty -overrides \
		-assembly:@prefix@/lib/mono/1.0/nunit.framework.dll -path:./nunit/en

That is, I run monodocer *twice* on each assembly, one under the 1.0
profile (to get any members we added from .NET 1.0), and again under the
2.0 profile (to get any members added from .NET 2.0).  (It's trivial to
expand this for .NET 3.0 -- just run monodocer again!)

You'll note the `-ignore_extra_docs' flag.  This is a (currently
private) addition which prevents the removal of members that aren't
found.  This is necessary so that repeated invocations don't remove
documentation -- e.g. you update the 2.0 docs, then re-run the process,
the 2.0 members won't be found in the 1.0 assemblies, and we don't want
these removed so that (1) their documentation is preserved, and (2)
they'll be present when we run against the 2.0 assemblies.

Then for good measure, the 2.0 update doesn't have -ignore_extra_docs,
under the assumption that 2.0 will have all the methods found in 1.0.

Alas, this assumption is wrong -- there are a number of members in
corlib 2.0 that are `#if !NET_2_0' -- they're only present under .NET
1.0.  Examples: System.Text.UnicodeEncoding.GetBytes(string), and there
are 17 others in mscorlib alone (I haven't tried this on anything else
yet).

Obviously, we don't want to remove these members...or do we?

The obvious fix is to add -ignore_extra_docs to the 2.0 generation, but
this means that if a member is ever added, it will never get deleted.
Perhaps this isn't a problem, perhaps it is.

What is becoming apparent is that 1.0 and 2.0 are sufficiently different
that saying "monodoc should document what the source code permits" is
impossible to do with complete accuracy.

Which leaves us with a few choices:

1. Live with the limitations, and use -ignore_extra_docs on 2.0
assemblies (thus implying that some members displayed in monodoc
actually exist in 2.0, which may not be true), or leave off
-ignore_extra_docs on 2.0 assemblies (so we lose some members/overrides
that were present in 1.0 but not 2.0).

2. Have separate documentation trees for 1.0 vs 2.0 assemblies.  This
mirrors the mdsn.microsoft.com vs msdn2.microsoft.com separation.  Alas,
this means documentation duplication, and we have enough problems
writing documentation that this probably isn't a good idea.

3. Find some way of removing the limitations of (1).  I'm not entirely
sure what this would entail -- perhaps having a monodocer mode where, if
a module is removed, it adds a Docs/removed element with the same value
as <since/>, e.g. <removed version=".NET 2.0" />.

3b. Modify the documentation format so that we explicitly state in which
versions a member exists, so instead of
a /Type/AssemblyInfo/AssemblyVersion element, we'd
have /Type/Members/Member/AssemblyInfo/AssemblyVersion elements, one for
each assembly version that contains this member.  Monodocer could then
know when an <AssemblyVersion/> can be removed (if the member was
deleted and the docs have an <AssemblyVersion/> identical to what
monodocer is currently processing), and if all <AssemblyVersion/>s are
removed then the member can be removed.

I'm open to other ideas...

Thanks,
 - Jon