> On 19 Mar 2015, at 02:49, Maruan Sahyoun <[email protected]> wrote: > > I'm about to start to enhance the documentation for PDFBox 2.0.0 with the > initial step to enhance the javadoc files (also covering xmpbox, preflight, > fontbox). > > Currently we have a rule - at least in Checkstyle - that a method returning a > non-void type should have a @return tag. That's not always the case and leads > to violations of the rule. So shall we either > > - disable the rule
Yes, please. As you mention, Google’s style guide has some good advice about this, specifically that: /*** * @return some value */ Is incorrect because @return tag text doesn't appear in class and method indexes in the JavaDoc, i.e. the method is actually missing a summary. Instead, they recommend using: /*** * Returns some value. */ Because the @return tag doesn’t add any useful information to the existing summary, e.g. if it were included we would be repeating ourselves: /*** * Returns some value. * @return some value */ If we could configure checkstyle to require the summary to be non-empty and to not require a @return tag, that would be ideal. — John > - or mandate it > > I'd go for mandating it as this will allow to tell that even for simple > methods if they are really so or if there is additional complexity. > > Good sample IMHO for a JavaDoc coding style > https://www.liferay.com/de/community/wiki/-/wiki/Main/Javadoc+Guidelines#section-Javadoc+Guidelines-Method+Javadoc+Tags > > > BR > Maruan > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
