Hi John, > Am 24.03.2015 um 19:25 schrieb John Hewson <j...@jahewson.com>: > > >> On 19 Mar 2015, at 02:49, Maruan Sahyoun <sahy...@fileaffairs.de> 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.
it's possible to configure checkstyle with some added rules like: minLineCount Minimal amount of lines in method to demand documentation presence. allowMissingJavadoc whether to ignore errors when a method javadoc is missed. allowMissingPropertyJavadoc Whether to allow missing Javadoc on accessor methods for properties (setters and getters). Current position from Andreas and myself is to keep mandating it. Let's see if there is further input. BR Maruan > > — 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: dev-unsubscr...@pdfbox.apache.org >> For additional commands, e-mail: dev-h...@pdfbox.apache.org >> > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@pdfbox.apache.org > For additional commands, e-mail: dev-h...@pdfbox.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@pdfbox.apache.org For additional commands, e-mail: dev-h...@pdfbox.apache.org
