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

[Jonathan Pryor]

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.  Without
having every released version of an assembly, we can't know in which
version a given type/member was introduced, especially since we only
have two sources of information: the assembly we're processing, and the
XML documentation we're attempting to update.

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.

Which may not be entirely problematic, but if it can be wrong we'll have
to expect the user to potentially update it, which makes this
information separate from the "normal" metadata (member name, parameter
& return types, etc.) which are *always* automatically generated &
checked.

So version information seems to be, by necessity, some "middle ground"
between pure metadata and user-modifiable data, especially since there's
no way to validate it (outside of Mike Kestner's DocVersionatorPlus).

>   That's what I was suggesting originally.  The
> strings are arbitrary to the extent any strings are, but at least
> they're parseable and able to be dealt with automatically by tools.

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.

> > Does the additional -since behavior described above satisfy this?
> 
> Yes, in part.  But I would rather not conflate user-written docs
> ("Version 2.0") with reliably formatted metadata (A.B.C.D) in the same node.

As mentioned above, I'm not convinced it's possible to completely
separate the user-written metadata from the "reliable metadata"
metadata.

> >>  stores the information in a non-structured way
> >> (opaque to other automated processes that might want to do something
> >> based on the info),
> > 
> > To be fair, /Type/AssemblyInfo/AssemblyVersion contains the same string,
> > or is a A.B.C.D string considered "structured"?
> 
> To me, yes.  It's in a reliable format mandated by the CLI specs,
> compared to unstructured user-written text that would go in the since
> tag.  Let's say we wanted to generated HTML docs just for the .NET 1.1
> libraries.  We can do this easily if we have the version as metadata.
> If not, we can only do it if we rely on a convention for how we write
> the since tags in the docs.

The since/@assembly-version attribute described above would permit this.

> >>  and introduces necessary redundancy by having the
> >> same user-given string "Version 2.0" distributed throughout all the
> >> types/members that appeared at the same time (which makes it difficult
> >> to revise without a find-replace across files).
> > 
> > And the solution to this would be a required "level of indirection", the
> > semantics and implementation of which escape me.
> 
> Yes for indirection, but simple in implementation.  If the types and
> members are already tagged with the version in reliable metadata, 

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

> one
> could easily list the nice/display names of versions once in the
> index.xml file or elsewhere, i.e.:
> 
> <Version Number="2.0.35.10" Name="Gtk# Version 2.0"/>
> 
> And that's if you really wanted to do that.  For lots of projects, it
> would probably be enough to just let the A.B.C.D format be displayed.
> 
> A nice compromise might be to just do both.  Keep the since tag as you
> have it now, but in addition add the version metadata to types and
> members as I described.  If a type/member has a since node, display it.
>  Otherwise, display the information from metadata.

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, since if
you wanted to change a version number (e.g. programmer mistake -- you
didn't update the AssemblyVersion attribute before re-running
monodocer), you'd *still* need to update all of the //Member/Version
elements across all the files.  There wouldn't be an intermediate "level
of indirection".

A true "level of indirection" would be something like a versions.xml
file specifying all known assembly versions, and then a //Member/Version
element which uses a string referencing an identifier within
versions.xml.  That way you could update only versions.xml and all
members which belong to this version would get the correct corresponding
display name.

Again, I see how this would work, but I don't see how it would work, if
you catch my drift.  What would be the version number strings mapping
the //Member/Version tag to the versions.xml tag?  It couldn't be e.g.
"2.1.3.4", as that looks like a real version number (and thus would
likely need to be changed, resulting in programmer confusion).  Anything
else would be more difficult to generate than I care to think about.

> Adding version metadata only adds, say, one line to each member, and we
> can change the current Type/../Assembly Version so it reflects the
> version the type was added, which means no new lines, and in fact that
> node will stop getting annoyingly updated with each version change.

Never changing /Type/AssemblyInfo is probably a good thing, but beyond
that I'm still not entirely sure I see all of the details and
ramifications of your proposal.

Perhaps some examples would help?

 - Jon