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

[Joshua Tauberer]

Jonathan Pryor wrote:
> Simple solution then: alter --since so that if an argument isn't
> provided it defaults to using the current assembly version.  So
> `--since' would insert <since version="1.2.3.4" /> while
> `--since="Version 1.2"' would insert <since version="Version 1.2" />.
> 
> Not sure how easy this is, but it sounds straightforward.

That's a possibility.

>> The --since
>> approach excludes the information from the meta-data section of the XML
>> documents, 
> 
> I'm still trying to figure out what this means.

The doc files are split with some parts for metadata and nothing
user-written and parts in the Docs section only for user-written docs
and no metadata.  I like that divide.  If the version is metadata, it
should go in the metadata section.

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

>> ignores the fact that it can be automatically determined from
>> the assembly version,
> 
> 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.

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

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

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.

How's that?

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