[
https://issues.apache.org/jira/browse/IO-438?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17729119#comment-17729119
]
Sebb commented on IO-438:
-------------------------
The Javadoc needs to be more specific as to when it is appropriate to use the
method.
The most important message is at
https://github.com/apache/commons-io/blob/5e3a4f1c172479633cb681f36c857473dda14dd5/src/main/java/org/apache/commons/io/IOUtils.java#L527
This applies to all the closeQuietly descriptions.
Maybe we could provide a full discussion in the first method, and reference
that from subsequent methods.
Also the examples (Closing all streams) at:
https://github.com/apache/commons-io/blob/5e3a4f1c172479633cb681f36c857473dda14dd5/src/main/java/org/apache/commons/io/IOUtils.java#L493
and
https://github.com/apache/commons-io/blob/5e3a4f1c172479633cb681f36c857473dda14dd5/src/main/java/org/apache/commons/io/IOUtils.java#L545
do not reflect best practice.
These examples should follow the preceding code sample which closes the stream
and handles errors.
Or just delete them, as they don't add anything useful once corrected.
> IOUtils.closeQuietly Javadoc needs fixing
> -----------------------------------------
>
> Key: IO-438
> URL: https://issues.apache.org/jira/browse/IO-438
> Project: Commons IO
> Issue Type: Bug
> Reporter: Sebb
> Priority: Major
>
> As mentioned in a comment on IO-388, there is a danger that closeQuietly is
> used inappropriately.
> Indeed the "Closing all streams:" examples in the Javadoc for various
> closeQuietly methods are wrong.
> The IOUtils.copy() methods don't close their input and output parameters.
> It is arguably OK to ignore exceptions when closing the input, but it is a
> bad idea to ignore exceptions when closing the output, as that could mean
> that the output has not been fully written.
> The Javadoc for these examples could be dropped, but I think it would be
> better to fix it to show how it should be done properly.
> There are a lot of copies of the bad example; I suggest we agree on a sample
> replacement before updating them all.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
