You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Bernd Eckenfels <ec...@zusammenkunft.net> on 2018/01/06 04:13:37 UTC
[IO-564] Javadoc inheritance for ByteArrayOutputStream.write
Hello,
Hao Zong reported some missing Details in the JavaDoc of ByteArrayOutputStream#write. While I dont think it is critical we should probably fix it, since a user asked for it.
I am willing to go through the streams of [IO] and adjust them, but I Need to know how:
a) Remove the JavaDoc of those overwritten API methods completely. This will inherit the JavaDoc from the official Stream classes which is in this case aproperiate and complete. This will make a good JavaDoc and shortst possible Code but the Code Looks underdocumented then.
b) Like a) but Keep a non-Javadoc comment giving the existing short description and a note to the effect of not having JavaDoc. This retains the full JavaDoc doc, the source is however a bit longer with a uncommon block comment.
c) Use javadoc with @{inheritDoc}. This makes it clear what is going on, however the @Throws documentation would Need to be replicated as it is not inherited.
d) Expand the existing documentation. This will take most work and space in the Code
Whats your Preference? I would really like to use a) in this case, is this acceptable?
Gruss
Bernd
--
http://bernd.eckenfels.net
Von: Bernd Eckenfels (JIRA)
Gesendet: Montag, 25. Dezember 2017 15:24
An: issues@commons.apache.org
Betreff: [jira] [Commented] (IO-564) The rules of ByteArrayOutputStream.writeare not documented.
[ https://issues.apache.org/jira/browse/IO-564?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16303286#comment-16303286 ]
Bernd Eckenfels commented on IO-564:
------------------------------------
The functionality is defined in the `java.io.OutputStream`. It defines in the description some of the runtime exceptions. I am not sure if we should duplicate the description. Maybe inherit the doc?
> If off is negative, or len is negative, or off+len is greater than the length of the array b,
> then an IndexOutOfBoundsException is thrown.
Also when we copy the description, should we use @throws for IOOBE and NPE?
> The rules of ByteArrayOutputStream.write are not documented.
> ------------------------------------------------------------
>
> Key: IO-564
> URL: https://issues.apache.org/jira/browse/IO-564
> Project: Commons IO
> Issue Type: Improvement
> Components: Streams/Writers
> Affects Versions: 2.6
> Reporter: Hao Zhong
>
> When I call the ByteArrayOutputStream.write method, it returns exceptions. Its API document is not quite useful, since it does not define any rules. From the thrown exceptions, I cannot get any useful information either. Until I read the code, I understand its usage:
> {code}
> public void write(final byte[] b, final int off, final int len) {
> if ((off < 0)
> || (off > b.length)
> || (len < 0)
> || ((off + len) > b.length)
> || ((off + len) < 0)) {
> throw new IndexOutOfBoundsException();
> } else if (len == 0) {
> return;
> }
> ...
> }
> {\code}
> Would you please explicitly introduce the rules in the doucment? Or, would you please add more messages to the thrown exception? Both ways can make the API easier to understand.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
Re: [IO-564] Javadoc inheritance for ByteArrayOutputStream.write
Posted by Pascal Schumacher <pa...@gmx.net>.
imho option a is acceptable
Am 06.01.2018 um 05:13 schrieb Bernd Eckenfels:
> Hello,
>
> Hao Zong reported some missing Details in the JavaDoc of ByteArrayOutputStream#write. While I dont think it is critical we should probably fix it, since a user asked for it.
>
> I am willing to go through the streams of [IO] and adjust them, but I Need to know how:
>
>
> a) Remove the JavaDoc of those overwritten API methods completely. This will inherit the JavaDoc from the official Stream classes which is in this case aproperiate and complete. This will make a good JavaDoc and shortst possible Code but the Code Looks underdocumented then.
> b) Like a) but Keep a non-Javadoc comment giving the existing short description and a note to the effect of not having JavaDoc. This retains the full JavaDoc doc, the source is however a bit longer with a uncommon block comment.
> c) Use javadoc with @{inheritDoc}. This makes it clear what is going on, however the @Throws documentation would Need to be replicated as it is not inherited.
> d) Expand the existing documentation. This will take most work and space in the Code
>
> Whats your Preference? I would really like to use a) in this case, is this acceptable?
>
>
> Gruss
> Bernd
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org