Comment 1 Frederic Fusier 2004-01-29 16:36:51 EST

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?

Comment 2 Jim des Rivieres 2004-01-29 17:44:24 EST

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".)

Comment 3 Frederic Fusier 2004-01-29 18:16:11 EST

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$

Comment 4 Philipe Mulet 2004-01-30 05:30:40 EST

Jim, 

Do you imply we should lose the term Javadoc in our implementation ?
It currently qualifies quite numerous internal pieces.

Comment 5 Jim des Rivieres 2004-01-30 10:22:38 EST

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. 

Comment 6 Philipe Mulet 2004-01-30 11:37:26 EST

We could perform a rename from Javadoc to Doc... 

Comment 7 Jim des Rivieres 2004-01-30 11:42:25 EST

I do not believe that it is a serious enough issue that would have us renaming 
code. Just be careful in published specs.

Comment 8 Frederic Fusier 2004-01-30 11:47:42 EST

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...

Comment 9 Jim des Rivieres 2004-01-30 12:44:53 EST

I've release changes:
- Removed "{}" from constants.
- Added missing specs.
- Added tests.

Comment 10 David Audel 2004-02-11 11:19:26 EST

Verified for 3.0M7