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 _______________________________________________ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list