commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernd Eckenfels <>
Subject [IO-564] Javadoc inheritance for ByteArrayOutputStream.write
Date Sat, 06 Jan 2018 04:13:37 GMT

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?


Von: Bernd Eckenfels (JIRA)
Gesendet: Montag, 25. Dezember 2017 15:24
Betreff: [jira] [Commented] (IO-564) The rules of ByteArrayOutputStream.writeare not documented.


Bernd Eckenfels commented on IO-564:

The functionality is defined in the ``. 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:
>             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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message