1:26 p.m.
Hi,
JavadocType checks whether each class/interface has javadoc.
How about enforcing that?
Ondra
1:28 p.m.
On 12/09/2011 01:26 PM, Ondřej Žižka wrote:
Hi,
JavadocType checks whether each class/interface has javadoc.
How about enforcing that?
I don't think its check is adequately configurable or robust. In
particular, I think it is OK to omit JavaDoc in the following cases:
* The class or member in question is non-public and not a serializable field
* The documentation may be inherited
I don't think the checkstyle check can be configured to handle this.
--
- DML
1:54 p.m.
Non-public:
<module name="JavadocType">
<property name="scope" value="public"/>
</module>
Inherited:
Javadoc is not required on a method that is tagged with the
@Override annotation. However under Java 5 it is not possible to mark a
method required for an interface (this was corrected under Java 6).
Hence Checkstyle supports using the convention of using a single
{@inheritDoc} tag instead of all the other tags.
Classes not mentioned.
However: Even inherited classes could have javadoc - with a summary of
in what way it extends or implements it's base or iface.
Ondra
David M. Lloyd píše v Pá 09. 12. 2011 v 13:28 -0600:
On 12/09/2011 01:26 PM, Ondřej Žižka wrote:
> Hi,
>
>
> JavadocType checks whether each class/interface has javadoc.
>
> How about enforcing that?
I don't think its check is adequately configurable or robust. In
particular, I think it is OK to omit JavaDoc in the following cases:
* The class or member in question is non-public and not a serializable field
* The documentation may be inherited
I don't think the checkstyle check can be configured to handle this.
9 p.m.
Note that if we enable this on existing code, we are going to see a lot
of failures and those will have to be fixed first. So yes, like Brian
says, we should probably look at this after 7.1.
-Jaikiran
On Saturday 10 December 2011 01:24 AM, Ondřej Žižka wrote:
Non-public:
<module name="JavadocType">
<property name="scope" value="public"/>
</module>
Inherited:
Javadoc is not required on a method that is tagged with the
@Override annotation. However under Java 5 it is not possible to mark
a method required for an interface (this was /corrected/ under Java 6).
Hence Checkstyle supports using the convention of using a single
{@inheritDoc} tag instead of all the other tags.
Classes not mentioned.
However: Even inherited classes could have javadoc - with a summary
of in what way it extends or implements it's base or iface.
Ondra
David M. Lloyd píše v Pá 09. 12. 2011 v 13:28 -0600:
> On 12/09/2011 01:26 PM, Ondřej Žižka wrote:
> > Hi,
> >
> >
> > JavadocType checks whether each class/interface has javadoc.
> >
> > How about enforcing that?
>
> I don't think its check is adequately configurable or robust. In
> particular, I think it is OK to omit JavaDoc in the following cases:
>
> * The class or member in question is non-public and not a serializable field
> * The documentation may be inherited
>
> I don't think the checkstyle check can be configured to handle this.
>
_______________________________________________
jboss-as7-dev mailing list
jboss-as7-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
2:06 p.m.
Sounds like something to consider for 7.2.
On 12/9/11 1:26 PM, Ondřej Žižka wrote:
Hi,
JavadocType checks whether each class/interface has javadoc.
How about enforcing that?
Ondra
_______________________________________________
jboss-as7-dev mailing list
jboss-as7-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
--
Brian Stansberry
Principal Software Engineer
JBoss by Red Hat
4781
days inactive
4782
days old
4 comments
4 participants
participants (4)
-
Brian Stansberry -
David M. Lloyd -
Jaikiran Pai -
Ondřej Žižka