Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] API scan for I-I200511281843-200511281843 is available

I think putting the @see comment with two asterisks is the wrong answer. If you put this:

/**
* @see  <method overridden>
*/

Then that is what will appear in the generated javadoc for that method. I.e., it will not show the javadoc from super type method. This is the convention that is typically used:

/*
* @see  <method overridden>
*/

This is because javadoc will automatically copy javadoc from the inherited method when a method has no javadoc at all. Admittedly removing the asterisk to make javadoc do the right thing is a bit of a hack.  Luckily, the @inheritDoc tag now exists so you can have the best of both worlds.  You can now have a real javadoc comment in your source code, and still inherit doc content from the parent method:

/**
 * {@inheritDoc}
 */

This allows you to augment the super-type doc with your own:

/**
 * {@inheritDoc}
 * <p>
 * This method overrides the super implementation to perform the following additional checks: ...
 * </p>
 */

Using @inheritDoc would make your API scanner happy, and allow you to inherit documentation from the super type.  For more info, see the javadoc doc:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@inheritDoc}

John



Jeffrey Liu/Toronto/IBM@IBMCA
Sent by: wtp-dev-bounces@xxxxxxxxxxx

30/11/2005 10:00 AM

Please respond to
"General discussion of project-wide or architectural issues."
To
"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc
Subject
Re: [wtp-dev] API scan for I-I200511281843-200511281843 is available






Amy,

Per discussion earlier, javadoc should start with 2 asterisks

/**
* @see  <method overridden>
*/

Also, the scanner will now account for javadoc inherited by overriding methods from superclass or interface (similar to what the Javadoc tool will do).

Thanks,

Jeffrey Liu
IBM Rational Software - Performance Analyst
IBM Toronto Lab.
8200 Warden Ave. Markham, Ontario, L6G 1C7
Internal mail: D3/R8V/8200/MKM (D3-268)
T/L: 969 3531
Tel: (905) 413 3531
Fax: (905) 413 4920
jeffliu@xxxxxxxxxx
Amy Wu <amywu@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

11/29/2005 10:57 AM

Please respond to
"General discussion of project-wide or architectural issues."
To
"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc
Subject
Re: [wtp-dev] API scan for I-I200511281843-200511281843 is available








I know some of the missing Javadoc for css, dtd, html, sse, jsp, xml, ui is because there are classes that extend other classes, so the methods overridden do not have JavaDoc.  Is JavaDoc really necessary in that case?  I suppose we can get around this by adding a comment like so:
/*
* @see  <method overridden>
*/

______________________________
Amy Wu
Structured Source Editor
919.254.0299, T/L 444.0299
amywu@xxxxxxxxxx
Arthur Ryman <ryman@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

11/29/2005 10:03 AM

Please respond to
"General discussion of project-wide or architectural issues."
To
"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc
Subject
Re: [wtp-dev] API scan for I-I200511281843-200511281843 is available







The latest API Progress Report is looking very encouraging overall. There are a few anomolies though.

Three WST components have 0 JUnit coverage:  css.ui, dtd.ui, html.ui. This seems odd. David - are there really no JUnits or are they just not being picked up? The Javadoc for these is also very low, but at there are only a few methods to document here. sse.ui is also in the red for both JUnit and Javadoc. jsp.ui and xml.ui have low Javadoc. These 6 components are candidates for deferal unless the numbers improve.

In JST j2ee.core is missing 600 Javadoc comments. I assume this is all in the generated EMF models. Chuck - can EMF generate Javadoc?

WST common.snippets is missing its Overview document. Craig - you are the wst.common component lead. Please add an Overview document for snippets.




Arthur Ryman,
IBM Software Group, Rational Division

blog: http://ryman.eclipsedevelopersjournal.com/
phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@xxxxxxx
Jeffrey Liu/Toronto/IBM@IBMCA
Sent by: wtp-dev-bounces@xxxxxxxxxxx

11/29/2005 09:34 AM

Please respond to
"General discussion of project-wide or architectural issues."
To
wtp-dev@xxxxxxxxxxx
cc
Subject
[wtp-dev] API scan for I-I200511281843-200511281843 is available








http://download.eclipse.org/webtools/committers/drops/I-I200511281843-200511281843/
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev

Back to the top