[Mono-docs-list] Documentation Updating...
latency at gmx.de
latency at gmx.de
Thu Jan 25 11:21:11 EST 2007
I would use the approach 3b. This seems to be the best solution for me since
it shows clearly when a member is present without those <since> <removed>
<again-since> <removed again> tags. In addition it would be similar to the
way microsoft has it's documentation organized. Each Member in MSDocs has
a "Available in:" note on the bottom.
But is this checking if a member can be removed or not necessary? In my
opinion marking the member with short <avaliable_in> tags would be enough.
On Friday 22 December 2006 16:22, Jonathan Pryor wrote:
> 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;
> 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)
> 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
> 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...
> - Jon
> Mono-docs-list maillist - Mono-docs-list at lists.ximian.com
More information about the Mono-docs-list