On Mon, Apr 6, 2009 at 1: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? > > Assuming people do agree that it's a bit better to avoid freeform text, then > Bob, I like your most recent suggestion with John's addendum.
The option to document the deprecation seems useful to me. Especially in the case that John mentioned--you may need to explain which parts of the big module got split into which chunk. I don't really like the idea that you have to provide a URL because it moves the documentation out of the module. I think one of the strengths of JavaDoc is that the doc is right there in the code. I'd like to suggest this format: <deprecated> <superceded-by module="...">Optional free-form text explaining this change</superceded-by> </deprecated> I think it's cleaner than a comma-separated superceded-by attribute and it allows you to document each replacement in-line. If people generally don't like the free-form text in line, then I'd vote for Bob's solution--an external file is likely to explain the whole change so it wouldn't make sense to replace my in-line text with an href on each superceded-by element. Ian --~--~---------~--~----~------------~-------~--~----~ http://groups.google.com/group/Google-Web-Toolkit-Contributors -~----------~----~----~----~------~----~------~--~---
