checkstyle

I want to use @see Tags in my Javadoc instead of @inheritDoc and configured
it in Eclipse with the Checkstyle-Plugin like this:

<module name="JavadocMethod">
<property name="scope" value="protected"/>
<property name="allowSeeTagInheritence" value="true"/>
</module>

Checkstyle throws problems, so I opened a bug report in eclipse-cs. They
told me:
"The mentioned allowSeeTagInheritence property is not part of the
Checkstyle distribution, since the bug was never fixed/closed."

When will the property be part of the distribution ?

Regards,

Achim

Logged In: YES
user_id=746148

1432907 (JavaDoc tag check doesn't consider Interface/@see
tag) was closed as duplicate of this bug

Logged In: YES
user_id=1619504

Hi --

I have extended the JavadocMethod, adding a new property:
allowSeeTagInheritence, defaulting to false.

Here's the code if you want to add it back in:

/**
* flag for allowing &lt;at>see tags instead of
{&lt;at>inheritDoc}.
*/
private boolean mAllowSeeTagInheritence;

/**
* Gets the flag for allowing &lt;at>see tags instead of
{&lt;at>inheritDoc}.
* @return the flag for allowing &lt;at>see tags instead
of {&lt;at>inheritDoc}.
*/
public boolean getAllowSeeTagInheritence()
{
return mAllowSeeTagInheritence;
}

/**
* Sets the flag for allowing &lt;at>see tags instead of
{&lt;at>inheritDoc}.
* @param flag flag for allowing &lt;at>see tags instead
of {&lt;at>inheritDoc}.
*/
public void setAllowSeeTagInheritence(boolean flag)
{
mAllowSeeTagInheritence = flag;
}

Then changed this code in the
JavadocMethodCheck#checkComment method:

// Check if see tag inheritence allowed.
boolean seeTagAllowed = getAllowSeeTagInheritence();
// Check for inheritDoc
boolean hasInheritDocTag = false;
while (it.hasNext() && !hasInheritDocTag)
{
JavadocTag tag = (JavadocTag) it.next();
hasInheritDocTag = seeTagAllowed ?
tag.isSeeOrInheritDocTag() : tag.isInheritDocTag();
}

And called like this:

<module
name="com.levworks.checkstyle.checks.javadoc.JavadocMethodCheck">
<property name="severity" value="error"/>
<!-- true allows just @see tag, false enforces
{@inheritDoc} -->
<property name="allowSeeTagInheritence" value="true"/>
</module>

Works great now... can we possibly include this
functionality in the next version so I can remove this
customization from my codebase?

Thanks,
Shanon

Logged In: YES
user_id=768885

Re-opening --

I agree with the comment that @see should be allowed as the
/only/ Javadoc, in addition to allowing it with other doc tags.

one example of where you must use @see instead of
{@inheritDoc} is subclasses of MappingDispatchAction in
Struts. The parent class defines an execute(args) method,
and subclasses define methods with various names like
save(args), edit(args), etc. They all have the same
signature as the execute method but different names, so
{@inheritDoc} won't work.

Logged In: YES
user_id=1250906

Not to allow @see as the only javadoc is a hugh problem for
existing code with tons of @see. Any @see must be replaced
with @inheritDoc (in lets says 10000 source files). So it
would be much much nicer if there were an option to again
allow @see as the only javadoc. The developer can than
switch to @inheritDoc for new sources.

Logged In: YES
user_id=746148

I've committed changes to CVS for 4.0b7(rc)
Now JavadocMethod check doesn't allow javadoc which contains
only @see tag.
If you want to see more improvements, feel free either
reopen this bug or file new with particular problem you want
to address here.

Logged In: YES
user_id=746148

Ok, it looks like no objections :)
Will work on this.

Logged In: YES
user_id=218824

I also agree that the change makes sense. Since we only
support JDK 1.4 and up, we can rely on the {@inheritDoc} tag
being valid.

Personally I only use the {@inheritDoc} tag these days.

Logged In: YES
user_id=746148

The request looks reasonable for me too.
I'd suggest to change the check (this means we will need to fix
pretty big number of problems in our sources ;)
What other developers think about this?