[Mono-docs-list] Monodocer <since/> support

[Jonathan Pryor]

On Wed, 2006-10-11 at 06:57 -0400, Joshua Tauberer wrote:
> Jonathan Pryor wrote:
> > (2) Command-line argument approach: add a ``--since name+version=tag''
> > argument, and if an assembly matching "name+version" is encountered,
> > create a <since/> element for any *added* types and members.

Rethinking this, I think a `--since=tag' would be sufficient, as
checking name+version seems superfluous now.

> It might be useful to decouple tracking which things were added in which
> assembly version from the <since/> tag with text used for display
> purposes.

Indeed, which is what Gtk# is already doing, using <since/> only for
display purposes.

> I played with adding versioning support a while back and what I came up
> with was something like what Jon had, but instead of inserting <since/>
> tags, it used the AssemblyVersion tags that already existed for types
> (and I guess I added them for members) to track the first version in
> which a type/member is seen.  When a type/member is stubbed for the
> first time, or for legacy docs with members without an AssemblyVersion
> tag, it inserts the AssemblyVersion.  But on future updates, it no
> longer modifies that information.  That leaves the AssemblyVersion with
> the first version in which the type/member appeared.

I'm less sure about this one, as I'm not sure I see the point.  What
would be the benefit to having an AssemblyVersion for every member?

> This also solves the annoying issue of every type XML file changing when
> the assembly version changes, because that tag doesn't get updated anymore.

As Mike mentioned, it would be nice to remove all assembly version
information from the Type.xml files.

> It doesn't work for back-versioning existing docs, like tagging things
> in the corlib with 1.0.*.*, since it will only insert the current
> assembly version on newly added types and all (legacy) members.  But
> updating the corlib is another issue entirely because we can't load the
> 1.0 corlib in monodocer anymore anyway.  (We can have a special system
> to back-version.)

Or we need to rethink monodocer being a .NET 2.0 app, and instead have
monodocer and monodocer2 for 1.0 and 2.0 profiles.  We could maintain
each using `#if NET_2_0' to split out the 2.0-specific code.

Though this probably doesn't matter either.  We'll want documentation
for the "latest and greatest assembly version" (mscorlib 2.0), and the
<since/> elements can specify which members were not in 1.0, so the lack
of a monodocer/monodocer2 split should be OK.

> Then the <since/> tag is left to display whatever you want.  But, since
> monodocer is already tracking the actual assembly version things were
> introduced in, it's possible to automatically insert documentation here
> with any format -- i.e. version 2.1.2.0 becomes "The 2.1 release of
> MyLib#.".  We can have a command line option that maps assembly versions
> to strings for since tags, overriding a default of just using the
> assembly version unchanged:
> 
>     --since 2.1.*.*="The 2.1 release."

Again, I'm not sure that monodocer needs to actually care about assembly
versions at all.

We could just do `--since "Gtk# 2.10"', and all new types/members would
get a "<since version="Gtk# 2.10" /> element inserted.  It would *only*
apply to added types/members, and there is no worry about
checking/comparing assembly versions or anything like that.

If `--since' isn't provided, then <since/> is never generated.

This is less "automagic", but it provides more control as well.

Thoughts?

 - Jon