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

[latency at gmx.de]

Hello,

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.

Kind Regards,
Valentin S.

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;
>
> 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
>
>
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list