Bugzilla – Full Text Bug Listing
| Summary: | DCR Javadoc AST: Offer well known tag names as constants | ||
|---|---|---|---|
| Product: | [Eclipse Project] JDT | Reporter: | Martin Aeschlimann <martinae> |
| Component: | Core | Assignee: | Frederic Fusier <frederic_fusier> |
| Status: | VERIFIED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P3 | CC: | jeem, philippe_mulet |
| Version: | 3.0 | ||
| Target Milestone: | 3.0 M7 | ||
| Hardware: | PC | ||
| OS: | Windows XP | ||
| Whiteboard: | |||
|
Description
Martin Aeschlimann
Here are proposed constants which would be added to org.eclipse.jdt.core.dom.TagElement: /** * Constants for well know javadoc tag names. */ public static final String TAG_DEPRECATED = "@deprecated"; //$NON-NLS-1$ public static final String TAG_PARAM = "@param"; //$NON-NLS-1$ public static final String TAG_RETURN = "@return"; //$NON-NLS-1$ public static final String TAG_THROWS = "@throws"; //$NON-NLS-1$ public static final String TAG_EXCEPTION = "@exception"; //$NON-NLS-1$ public static final String TAG_SEE = "@see"; //$NON-NLS-1$ public static final String TAG_LINK = "@link"; //$NON-NLS-1$ public static final String TAG_LINKPLAIN = "@linkplain"; //$NON-NLS-1$ public static final String TAG_INHERITDOC = "@inheritDoc"; //$NON-NLS-1$ Everybody agree on names? The naming scheme is good; TagElement is the right place for them. We might as well support the full set of 1.4.2 standard doc tags, as given in: http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html (btw, "Javadoc" is a Sun trademark. We should be careful to refer to them as "doc comments and tags", rather than as "Javadoc comments and tags".) Thanks Jim. So following tags were also added:
public static final String TAG_AUTHOR = "@author"; //$NON-NLS-1$
public static final String TAG_DOCROOT = "{@docRoot}"; //$NON-NLS-1$
public static final String TAG_SERIAL = "@serial"; //$NON-NLS-1$
public static final String TAG_SERIALDATA= "@serialData"; //$NON-NLS-1$
public static final String TAG_SERIALFIELD= "@serialField"; //$NON-NLS-1
$
public static final String TAG_SINCE = "@since"; //$NON-NLS-1$
public static final String TAG_VALUE= "{@value}"; //$NON-NLS-1$
public static final String TAG_VERSION = "@version"; //$NON-NLS-1$
Jim, Do you imply we should lose the term Javadoc in our implementation ? It currently qualifies quite numerous internal pieces. Re: comment #3 - The string values for embedded tags should not include "{}". Re: comment #4 - We're obviously stuck with some API classes and methods with "Javadoc" in them. Both "Java" and "Javadoc" being Sun trademarks, we need to be careful to use them properly. The Javadoc specs which get published in Help books are where we need to be most careful. We could perform a rename from Javadoc to Doc... I do not believe that it is a serious enough issue that would have us renaming code. Just be careful in published specs. If we do not intend to change CompilerOptions names to avoid (again)
compatibility problems, i think renaming would offer advantage to be compliant
with DOM AST API terms use in comments
But isn't 'Doc' too short and may be a little bit too generic?
I would prefer DocComment, it's longer but more explicit.
I can reopen the bug to use it first to fix {} error and handle this renaming,
but keep target for M7...
I've release changes:
- Removed "{}" from constants.
- Added missing specs.
- Added tests.
Verified for 3.0M7 |