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

[Jonathan Pryor]

I suspect <since/> support is going to need a re-think, to determine
what the workflow is supposed to be.  More below.

On Tue, 2006-10-10 at 10:17 -0500, Mike Kestner wrote:
> 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.

Which brings up the fatal problem with the current approach: updates.
Since the current approach will update the Assembly version within
index.xml during execution, you will only get <since/> elements inserted
*once*, the *first* time you update against a given version of the
assembly.

Oops.

So given a (presumably typical) workflow of (a) make changes, (b)
generate docs, (c) repeat, you won't get any additional <since/> tags on
every (b) invocation after the first cycle.  This is a fundamentally
fatal problem.

It also doesn't handle parallel versions -- we have a large part of .NET
1.0 implemented, but once we migrate the docs to target 2.0 we'll
presumably need a decent way to add docs for any 1.0 members introduced
later.

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

So, what workflow do we want to support?

> I think this is a better approach, having a one-time tool that seeds the
> versioning info onto the doc tree.

I'm not entirely sure.  More below.

> If it were up to me, I'd completely avoid assembly information in
> monodoc sources.

I agree, we can't use any assembly information within the XML files, as
this breaks when you need to support multiple versions concurrently
(e.g. mscorlib.dll docs for 1.0, 2.0, 3.0...).

So before fixing the implementation, we need to determine what workflow
we want to support.  I see two approaches:

(1) The DocVersionatorPlus approach, in which you have two assemblies,
and a program which compares the members of the two assemblies and
inserts <since/> elements for each member added in the later version.

I'm not fond of this idea, as it requires having two versions of the
assembly around.  For a normal svn checkout, you'll only have the
sources to the current version, requiring extra "bookkeeping" on the
developer's part to keep the previous version around.

Workflow:

  a Update assembly
  b Generate docs for new types/members; <since/> NOT inserted.
  c repeat a..b until done
  d run DocVersionatorPlus on previous assembly & current assembly to 
    insert <since/> elements.

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

This is basically the current <since/> implementation without the
implicit dependency on index.xml assembly versions.  Instead, the
assembly names + versions are on the command line.

So when creating stubs for an assembly matching the --since name+version
argument, a <since version="tag" /> element is created.

This removes all dependencies on the XML to store version information,
allows subsequent updates to continue inserting <since/> elements even
if the assembly version doesn't change (as long as the assembly version
matches the --since argument it'll get a <since/> element), and doesn't
require the presence of a second assembly for version comparisons.

Workflow:

  a Update assembly
  b Generate docs for new types/members; <since/> *IS* inserted.
  c repeat a..b until done.

Is there an alternate workflow that would be useful?  Is there a
preferred workflow among these choices?

Thanks,
 - Jon