You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pdfbox.apache.org by Maruan Sahyoun <sa...@fileaffairs.de> on 2015/03/19 10:49:15 UTC
PDFBox 2.0 and documentation
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
- 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-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: PDFBox 2.0 and documentation
Posted by John Hewson <jo...@jahewson.com>.
> On 24 Mar 2015, at 11:44, Maruan Sahyoun <sa...@fileaffairs.de> wrote:
>
> Hi John,
>
>> Am 24.03.2015 um 19:25 schrieb John Hewson <jo...@jahewson.com>:
>>
>>
>>> On 19 Mar 2015, at 02:49, Maruan Sahyoun <sa...@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-unsubscribe@pdfbox.apache.org
>>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: PDFBox 2.0 and documentation
Posted by Maruan Sahyoun <sa...@fileaffairs.de>.
Hi John,
> Am 24.03.2015 um 19:25 schrieb John Hewson <jo...@jahewson.com>:
>
>
>> On 19 Mar 2015, at 02:49, Maruan Sahyoun <sa...@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-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: PDFBox 2.0 and documentation
Posted by John Hewson <jo...@jahewson.com>.
> On 19 Mar 2015, at 02:49, Maruan Sahyoun <sa...@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.
— 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-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: PDFBox 2.0 and documentation
Posted by Maruan Sahyoun <sa...@fileaffairs.de>.
> Am 19.03.2015 um 18:37 schrieb Tilman Hausherr <TH...@t-online.de>:
>
> John once mentioned that "Returns xxx" is legit according to an Oracle java style guide. My own IDE (which is developed by Oracle) brings out a warning.
>
> http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return
>
I think he mentioned Googles style guide http://google-styleguide.googlecode.com/svn/trunk/javaguide.html#s7.3.1-javadoc-exception-self-explanatory <http://google-styleguide.googlecode.com/svn/trunk/javaguide.html#s7.3.1-javadoc-exception-self-explanatory> if I remember correctly.
> Tilman
>
> Am 19.03.2015 um 10:49 schrieb Maruan Sahyoun:
>> 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
>> - 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-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
Re: PDFBox 2.0 and documentation
Posted by Tilman Hausherr <TH...@t-online.de>.
John once mentioned that "Returns xxx" is legit according to an Oracle
java style guide. My own IDE (which is developed by Oracle) brings out a
warning.
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return
Tilman
Am 19.03.2015 um 10:49 schrieb Maruan Sahyoun:
> 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
> - 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-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: PDFBox 2.0 and documentation
Posted by Andreas Lehmkuehler <an...@lehmi.de>.
Hi,
Am 19.03.2015 um 10:49 schrieb Maruan Sahyoun:
> 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
> - 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.
+1, we should follow our own rules. They exists for years and I don't see any
good reason to change them. If we would make such docs optional people tend to
not to add them even in complex cases.
> 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-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
BR
Andreas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org