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

[Jonathan Pryor]

On Thu, 2006-10-12 at 08:49 -0400, Joshua Tauberer wrote:
> I guess what bothers me is that the version in which a type/member
> appears is very meta-data like (meta-meta-data), automatically
> determinable, structured (i.e. in the A.B.C.D format), and consistent
> across all types/members introduced in the same version.

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.

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

> ignores the fact that it can be automatically determined from
> the assembly version,

Does the additional -since behavior described above satisfy this?

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

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

:-)

I have no doubt that things could be better.

I just don't know what "better" would be.

Thanks,
 - Jon