lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Michael Osipov (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (LUCENE-4525) JavaDoc of SearcherManager#close is not crystal clear
Date Fri, 02 Nov 2012 11:25:12 GMT

    [ https://issues.apache.org/jira/browse/LUCENE-4525?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13489365#comment-13489365
] 

Michael Osipov commented on LUCENE-4525:
----------------------------------------

The patch is incomplete, @throws is missing on:

- acquire
- afterClose
- decRef
- refreshIfNeeded
- release

While most of them a checked exceptions and are visible anyway, unchecked unexceptions aren't
visible until you hit them or document properly.

The close() has some errors, here is a corrected version:

{noformat}
    * <p>
    * Close this ReferenceManager to prevent future {@link #acquire() acquiring}. A
    * reference manager should be closed if the reference to the managed resource
    * should be disposed or the application using the {@link ReferenceManager}
    * is shutting down. The managed resource might not be released immediately,
    * if the {@link ReferenceManager} user is holding on to a previously
    * {@link #acquire() acquired} reference. The resource will be released once
    * when the last reference is {@link #release(Object) released}. Those
    * references can still be used as if the manager was still active.
    * </p>
    * <p>
    * Applications should not {@link #acquire() acquire} references from this
    * manager once this method has been called. {@link #acquire() Acquiring} a
    * resource on a closed {@link ReferenceManager} will throw an
    * {@link AlreadyClosedException}.
    * </p>
    * 
    * @throws IOException
    *           if the underlying reader of the current reference could not be closed
{noformat}

I have changed especially the @throws tag because I do not see as a user any connection between
a decRef and an IOE w/o reading further JavaDocs.

Thanks!
                
> JavaDoc of SearcherManager#close is not crystal clear
> -----------------------------------------------------
>
>                 Key: LUCENE-4525
>                 URL: https://issues.apache.org/jira/browse/LUCENE-4525
>             Project: Lucene - Core
>          Issue Type: Improvement
>          Components: core/search
>    Affects Versions: 3.6.1, 4.0
>            Reporter: Michael Osipov
>            Assignee: Simon Willnauer
>            Priority: Minor
>         Attachments: LUCENE-4525.patch
>
>
> Raised from http://www.mail-archive.com/java-user@lucene.apache.org/msg40064.html
> The JavaDoc says:
> {noformat}
>   /**
>    * Close this ReferenceManager to future {@link #acquire() acquiring}. Any
>    * references that were previously {@link #acquire() acquired} won't be
>    * affected, and they should still be {@link #release released} when they are
>    * not needed anymore.
>    */
> {noformat}
> The first sentence is not really clear. I would expect something like:
> {noformat}
> Close this ReferenceManager when the application is shutting down or the
>  underlying index will be disposed. Any references that were previously
>  {@link #acquire() acquired} won't be affected, and they should still be 
> {@link #release released} when they are not needed anymore.
> {noformat}
> Further more, the JavaDoc does not declare that an exception will be thrown on any method.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message