Oh, and... as much as I hate to suggest it, we will probably need some way to suppress the deprecation warning.
Maybe: <inherits name="example.module.Foo" ignore-deprecation="true" /> Where ignore-deprecation is optional and defaults to false. I'm tempted to say that ignore-deprecation="true" on a non-deprecated module produces a warning, just to discourage premature ignoring. On Tue, Apr 7, 2009 at 9:15 AM, Joel Webber <[email protected]> wrote: > 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 <[email protected]> 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 <[email protected]> wrote: >> > On Mon, Apr 6, 2009 at 4:51 PM, John Tamplin <[email protected]> wrote: >> >> >> >> On Mon, Apr 6, 2009 at 4:47 PM, Bruce Johnson <[email protected]> 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 -~----------~----~----~----~------~----~------~--~---
