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

[Joshua Tauberer]

Jonathan Pryor wrote:
> I'm still not entirely sure what your entire proposal is.  Is it to
> have two elements, //Member/Version and //Member/Docs/since, the
> former being automatically inserted while the latter is controlled by
> the user?

To answer this out of order and up front -- yes.

> On Fri, 2006-10-13 at 08:38 -0400, Joshua Tauberer wrote:
>>> Consider Gtk#, in which members were introduced in versions 2.4,
>>> 2.6, 2.8, 2.10... The /Type/AssemblyInfo/AssemblyVersion section
>>> of the XML documentation holds only *one* version, the current
>>> version, so I'm not sure how best to represent the myriad
>>> versions a member can come from that doesn't, to some extent,
>>> rely upon some arbitrary string (as since/@version uses).
>> We don't use Type/../AssemblyVersion for anything, so let's assume
>> we replace it with a new node (maybe at the same location) that has
>> the assembly version the type was introduced in, and every Member
>> also gets its own such node.
> 
> The problem I have with this is that it's potentially wrong.

Just to formalize the problem you point out, the version will be wrong
just when a type/member was added in a previous/now-outdated version
that was not yet monodocer'ed.

> So if someone is writing documentation for an assembly that has
> already had several releases (i.e. they're not writing docs
> concurrently with the code), or if they accidentally forget to modify
> the assembly version before running monodocer, or any number of other
> random mishaps which are likely to happen, the version information
> for the inserted member *will* be wrong.

Those same problems happen with the --since method, and in both cases
(metadata vs --since) you end up with wrong stuff that is non-trivial to
correct.  (Not impossible or even difficult if you still have an older
version of the assembly around.)  So I agree that version metadata has a
sort of less-reliable quality that the rest of the metadata, but I don't
see it as a compelling reason to abandon the information completely.

> Which may not be entirely problematic, but if it can be wrong we'll
> have to expect the user to potentially update it

We can have an option in monodocer so the user can provide an older
assembly to back-version items: both back-versioning the metadata as
well as correcting --since tags that should have had previous versions.

> To mutilate an idea you propose later, perhaps we could add an
> attribute to the <since/> element which contains the current assembly
> version, e.g.
> 
> <since version="Gtk# 2.4" assembly-version="2.4.0.0" />
> 
> though I'm not sure this actually buys anything, for the reasons
> listed above.

You don't mean "current" (as in what's put in
/Type/Assembly/AssemblyVersion) but the version that corresponds with
the "version" attribute, I think?  Are you suggesting it be
automatically inserted or user-written?

> Hence my problem, I don't see any way for the version information to 
> ever be considered "reliable"...

I didn't really mean reliable as in something like "assuredly correct".
 I was going for something like "the node will assuredly contain a valid
A.B.C.D version string which is no earlier than the version in which the
type/member appeared, and provided the user runs monodocer on every
released version, then it will actually *be* that version."

That's close enough for me.  The information is no less reliable than
the <since/> tag, and in just the same cases where the since tag is
reliable (i.e. correct), the metadata version is not only reliable (i.e.
correct) but also machine-readable.

> I'm still not entirely sure what your entire proposal is.  Is it to
> have two elements, //Member/Version and //Member/Docs/since, the
> former being automatically inserted while the latter is controlled by
> the user?
> 
> If so, this still doesn't permit easy change across all files

Ok.  Nevermind.  Updating metadata is slightly easier, but not so much
that it makes a difference.  (In order to back-version a type/member to
a version that you forgot to run monodocer on, you only need the old
assembly to update the metadata.  Any type/member present in the
assembly and the docs that has a future version set just gets reduced to
the old version number.  To update a <since/> tag, you need the old and
prior-to-that assemblies at the same time so you can figure out which
members were added in just that version.)

So here's my scenario.  I have a Makefile that runs monodocer whenever I
build my deployment package.  So, monodocer gets run on every released
version, which means that the version metadata will be kept up-to-date.
  Further, in my HTML docs I'm happy to list members as being since some
A.B.C.D version. In this case, I can leave version tracking entirely to
monodocer.  If I use --since, I have to remember to update it after each
release, and further I would be specifying the exact same thing that
monodocer could be figuring out for itself.

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