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

[Joshua Tauberer]

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.

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.

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.

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.

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.)

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."

(actually I would recommend not using asterisks on the command line, of
course, but that shows what I meant)

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man. You're
about to have a truth-mitzvah."  -- The Colbert Report