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

[Mike Kestner]

Hey guys.  Sorry I haven't chimed in sooner.  Thanks for working on
this.  I've grown tired of yank/pasting since tags in Gtk#.  ;-)

On Tue, 2006-10-10 at 08:44 -0400, Jonathan Pryor wrote:

>   - During Type/member processing, check to see if the assembly name
> this type is from is within the list generated above.  If the assembly
> is found, *and* the version of the current assembly is greater than the
> assembly version stored above, create a <since/> element with a version
> attribute containing the current assembly version, e.g.
> 
> 	<since version="0.1.0.0" />

In Gtk#, I use version="Gtk# 2.x" for my since tags.  Inserting the full
assembly version information is a little overkill, and problematic for
anyone documenting unstable assembly versions as they go.  I think the
ability to specify the version string needs to be exposed by cmdline
parameter, or possibly using stdin during execution if new elements are
detected.

> Very simple, very braindead, but should be fairly functional, and should
> allow us to run `monodocer' on the class libs and get <since/> elements
> generated for all of the types and members that were added in .NET 2.0.

For Gtk#, I created a separate utility I codenamed DocVersionatorPlus
for seeding the files.  It used reflection on two assemblies and
inserted a since tag for any API elements that existed in the "new"
assembly and weren't in the "old" assembly.  This allowed me to
systematically add tags for 3 released versions, and _not_ have any
since tags on the base 1.0 version elements.

I still have the source for DVP, though it copy/pasted a substantial
amount of monodocer at the time and I've made no effort to keep it in
sync.  My intention had been to extract the shared monodocer source into
a separate source file and build both tools from that, but
unfortunately, once the Gtk# docs were versioned, my motivation went out
the window.  ;-)  If anyone is remotely interested in pursuing that
direction, I'd be happy to contribute DVP source code.

I think this is a better approach, having a one-time tool that seeds the
versioning info onto the doc tree.  Then the version insertion part of
monodocer can be as simple as:

if adding_member then maybe_add_since_tag

with the appropriate querying for the version text and a little extra
juice to avoid adding duplicate since tags on members when the type has
the same since version.

If it were up to me, I'd completely avoid assembly information in
monodoc sources.  We can't remove it at this point, but it clutters up
the files with mostly useless information, and makes more work for
anyone who is actually documenting as they go and using unstable
assembly versions during a development interval.  I think we should
avoid adding new capabilities to monodocer that rely on them.

-- 
Mike Kestner  <mkestner at novell.com>
SUSE® Linux Enterprise 10
Your Linux is ready™
www.novell.com/linux