> On 24 Mar 2015, at 11:44, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: > > 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).
Hmm, none of those are quite right. We want to ensure that a summary is present, not just @tags. > 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 > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@pdfbox.apache.org For additional commands, e-mail: dev-h...@pdfbox.apache.org
