I have to say I'm with Isaac on this one. I think it's best to keep things as simple as possible, and to keep the documentation in one place wherever possible. There's nothing stopping anyone from putting URLs in the explanatory text if they want, but I wouldn't want to have to do that in the default case. I also prefer to *not* create an overly-structured way to express deprecation, when it's nigh-impossible to think of all the possible ways people may want to deprecate things. That said, I don't think it's unreasonable to accept a simple list of superceded-by modules.
On Tue, Apr 7, 2009 at 8:37 AM, Isaac Truett <itru...@gmail.com> wrote: > > I'd vote for a consistent message supplied by the compiler/hosted mode > and freeform text provided by the module developer. I think that works > fine for JavaDoc @deprecated. URLs and the names of successor modules > can be included in the freeform text when appropriate. Unless you're > planning to plug those things into a template somewhere, why do you > need to separate them from the block of text? > > Example deprecated module: > > <module> > ... > <deprecated>WARNING: Use of this module may result in permanent loss > of productivity. Whatever you were doing with it before was wrong, so > just stop already!</deprecated> > </module> > > Example error message: > > Module foo inherits deprecated module bar. > > WARNING: Use of this module may result in permanent loss of > productivity. Whatever you were doing with it before was wrong, so > just stop already! > > > In this contrived example, there's no URL or replacement to suggest. > There isn't much information available except for the freeform text. > > > > On Mon, Apr 6, 2009 at 4:53 PM, Bruce Johnson <br...@google.com> wrote: > > On Mon, Apr 6, 2009 at 4:51 PM, John Tamplin <j...@google.com> wrote: > >> > >> On Mon, Apr 6, 2009 at 4:47 PM, Bruce Johnson <br...@google.com> wrote: > >>> > >>> (BTW, I could be wrong about the whole "let's not have freeform text". > It > >>> was just one guy's opinion that it makes things too inconsistent. I'd > like > >>> to hear if other people agree/disagree.) > >>> > >>> @Other people: agree/disagree? > >> > >> I think there may be some case where you want/need more explanation, > >> especially if it is of the form "If you were doing X, use module A -- if > you > >> were doing Y, use module B". However, I think the URL will address most > of > >> that and it is easy enough to extend it later for free-form text if it > >> becomes useful to do so -- it is harder to remove it if we add it now > but it > >> isn't useful. > >> > >> The one question I have is where will the URL point for an unreleased > >> version? Ie, say we deprecate something in trunk, where would we make > the > >> URL point for more information? > > > > The compiler does this already by including reference to HTML files that > are > > included in the distro. It is important that this could work (i.e. file > > URLs). > > > > > > > > > > > --~--~---------~--~----~------------~-------~--~----~ http://groups.google.com/group/Google-Web-Toolkit-Contributors -~----------~----~----~----~------~----~------~--~---
