Comments in empty blocks / JavaDoc of interface method implementations

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Comments in empty blocks / JavaDoc of interface method implementations

Martin Burger
Hello,

I'm using Checkstyle for a few days - it's very impressive. However, for
my intended purpose it has two disadvantages:


Checks for empty blocks

I agree that blocks should not be empty, especially exceptions should
not be ignored. But, there are good exemption of this rule. Consentient
to Joshua Bloch's Item 47: "At the very least, the catch block should
contain a comment explaining why it is appropriate to ignore the exception."

I found no way to configure the check EmptyBlock to not complain about
blocks containing just a comment.


Checks the Javadoc of a method or constructor

As described at http://dev.eclipse.org/javadoc.html it is (may) not
advisable to add JavaDoc comments to interface method implementations.

How can I configure the check JavadocMethod to ignore the "missing"
JavaDoc of such methods?


Perhaps I missed something in the manual, but I found no solution for
these two issues. Does anybody know a solution?

Regards,
    Martin


-------------------------------------------------------
This SF.Net email is sponsored by: NEC IT Guy Games.  How far can you shotput
a projector? How fast can you ride your desk chair down the office luge track?
If you want to score the big prize, get to know the little guy.  
Play to win an NEC 61" plasma display: http://www.necitguy.com/?r=20
_______________________________________________
Checkstyle-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/checkstyle-user
Reply | Threaded
Open this post in threaded view
|

Re: Comments in empty blocks / JavaDoc of interface method implementations

Oliver Burn
If you look at the documentation for EmptyBlock at http://checkstyle.sourceforge.net/config_blocks.html#EmptyBlock you will see it supports the property option. The valid values are documented at http://checkstyle.sourceforge.net/property_types.html#block and it supports the option text which is exactly what you want.

For methods that are an implementation of an interface, I document with the text "/** {@inheritDoc} */" as documented at http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod.

Regards,
Oliver

Martin Burger wrote:
Hello,

I'm using Checkstyle for a few days - it's very impressive. However, for my intended purpose it has two disadvantages:


Checks for empty blocks

I agree that blocks should not be empty, especially exceptions should not be ignored. But, there are good exemption of this rule. Consentient to Joshua Bloch's Item 47: "At the very least, the catch block should contain a comment explaining why it is appropriate to ignore the exception."

I found no way to configure the check EmptyBlock to not complain about blocks containing just a comment.


Checks the Javadoc of a method or constructor

As described at http://dev.eclipse.org/javadoc.html it is (may) not advisable to add JavaDoc comments to interface method implementations.

How can I configure the check JavadocMethod to ignore the "missing" JavaDoc of such methods?


Perhaps I missed something in the manual, but I found no solution for these two issues. Does anybody know a solution?

Regards,
   Martin


-------------------------------------------------------
This SF.Net email is sponsored by: NEC IT Guy Games.  How far can you shotput
a projector? How fast can you ride your desk chair down the office luge track?
If you want to score the big prize, get to know the little guy.  Play to win an NEC 61" plasma display: http://www.necitguy.com/?r=20
_______________________________________________
Checkstyle-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/checkstyle-user

Reply | Threaded
Open this post in threaded view
|

Re: Comments in empty blocks / JavaDoc of interface method implementations

Martin Burger
Oliver Burn schrieb am 14.06.2005 12:13:

> If you look at the documentation for EmptyBlock at
> http://checkstyle.sourceforge.net/config_blocks.html#EmptyBlock you
> will see it supports the property *option*. The valid values are
> documented at
> http://checkstyle.sourceforge.net/property_types.html#block and it
> supports the option *text *which is exactly what you want.
>
> For methods that are an implementation of an interface, I document
> with the text "/** {@inheritDoc} */" as documented at
> http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod.


Oh, I have to read the docs much more carefully. Thanks for your assistance.

Regards
    Martin


-------------------------------------------------------
This SF.Net email is sponsored by: NEC IT Guy Games.  How far can you shotput
a projector? How fast can you ride your desk chair down the office luge track?
If you want to score the big prize, get to know the little guy.  
Play to win an NEC 61" plasma display: http://www.necitguy.com/?r=20
_______________________________________________
Checkstyle-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/checkstyle-user
Reply | Threaded
Open this post in threaded view
|

Re: Comments in empty blocks / JavaDoc of interface method implementations

Martin Burger
In reply to this post by Oliver Burn
Oliver Burn schrieb am 14.06.2005 12:13:
For methods that are an implementation of an interface, I document with the text "/** {@inheritDoc} */" as documented at http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod.

Eclipse runs into trouble when using the {@inheritDoc} code. Is it possible to configure the check JavadocMethod to ignore the "missing" JavaDoc?

Regards,
    Martin





	
	
	
	
Reply | Threaded
Open this post in threaded view
|

Re: Comments in empty blocks / JavaDoc of interface method implementations

Oliver Burn
Did you read the documentation at
http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod

If so, you obviously missed the 'allowMissingJavadoc' flag. :-)

Oliver

> Oliver Burn schrieb am 14.06.2005 12:13:
>
>> For methods that are an implementation of an interface, I document
>> with the text "/** {@inheritDoc} */" as documented at
>> http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod.
>
>
> Eclipse runs into trouble
> <https://bugs.eclipse.org/bugs/show_bug.cgi?id=24227> when using the
> {@inheritDoc} code. Is it possible to configure the check JavadocMethod
> to ignore the "missing" JavaDoc?
>
> Regards,
>     Martin
>
>




-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Checkstyle-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/checkstyle-user