You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Tomer Gabel (JIRA)" <ji...@apache.org> on 2009/06/01 06:30:07 UTC
[jira] Created: (LUCENE-1670) Cosmetic JavaDoc updates
Cosmetic JavaDoc updates
------------------------
Key: LUCENE-1670
URL: https://issues.apache.org/jira/browse/LUCENE-1670
Project: Lucene - Java
Issue Type: Improvement
Components: Javadocs
Affects Versions: 2.4.2
Environment: Lucene SVN (diff from r780545)
Reporter: Tomer Gabel
Priority: Trivial
Fix For: 2.4.2
I've taken the liberty of making a few cosmetic updates to various JavaDocs:
* MergePolicy (minor cosmetic change)
* LogMergePolicy (minor cosmetic change)
* IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
Attached diff from SVN r780545.
I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12714998#action_12714998 ]
Tomer Gabel commented on LUCENE-1670:
-------------------------------------
Alright, I'll attach a new patch in a couple of minutes that has the following improvements:
* LogMergePolicy: You are correct. I removed the links, as well as tried rewriting the paragraph to be a little clearer.
* MergePolicy: This is not a problem; it does not appear in the API, but it's still linked (hence refactoring tools such as Eclipse will update the link value as well as the class name), and it shows in monospaced font as you'd expect with <code>.
* IndexWriter: Re (3), the extra token is the apparent text for the link (in this case, it "hides" the parameters). I merely "translated" from the previous anchor tag to links.
* IndexWriter: Fixed a few typoes
* IndexWriter: Reverted the mergePolicy link change
* IndexWriter: Fixed missing IndexSearcher import for link
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Shai Erera (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12714980#action_12714980 ]
Shai Erera commented on LUCENE-1670:
------------------------------------
I have a couple of comments:
# In LogMergePolicy, you add a reference to mergeFactor ({@link #mergeFactor}), which is a private member of LMP. Wouldn't that be an issue when generating the javadocs (i.e., create a link to a non-existent entity, since private members are not generated in the javadocs)?
# In MergePolicy you added a link to SegmentInfo. Same as above - SegmentInfo is package private and therefore I'm not sure its included in the javadocs. If I look here (http://lucene.apache.org/java/2_4_0/api/core/index.html), SegmentInfo does not appear there.
# In IndexWriter, you add references like this: {@link #addDocument(Document) addDocument} - is the 'addDocument' in the end necessary. I've tried it and it doesn't come out nicely in the javadocs. Same goes for {@link #updateDocument(Term, Document) updateDocument}.
# In IndexWriter you replaced *see <a href="#mergePolicy">* with *see {@link #mergePolicy below}* - that's wrong for two reasons: (1) mergePolicy is private (see comments above) and (2) the javadocs actually have an element afterwards: *<a name="mergePolicy"></a>*. The part you replaced references that element, rather than the mergePolicy member (which just happen to have the same name :)).
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Updated: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Tomer Gabel updated LUCENE-1670:
--------------------------------
Attachment: lucene_1670.patch
Patch against r780545
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12715077#action_12715077 ]
Tomer Gabel commented on LUCENE-1670:
-------------------------------------
That's odd -- one of the changes I made in the second version was to fix that precise warning (added an import directive). The last bullet even mentions it :-/
Anyway glad to be of help!
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Assignee: Michael McCandless
> Priority: Trivial
> Fix For: 2.9
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Updated: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Tomer Gabel updated LUCENE-1670:
--------------------------------
Attachment: (was: lucene_1670.patch)
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Resolved: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Michael McCandless (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Michael McCandless resolved LUCENE-1670.
----------------------------------------
Resolution: Fixed
Fix Version/s: (was: 2.4.2)
2.9
Thanks Tomer! I just committed this. There was one warning the patched caused when running "ant javadocs-core":
{code}
[javadoc] /lucene/src/clean/src/java/org/apache/lucene/index/IndexWriter.java:215: warning - Tag @link: reference not found: IndexSearcher
{code}
(because IndexSearcher wasn't imported in IndexWrieter.java). So I just reverted that change (made it fully qualified again).
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Assignee: Michael McCandless
> Priority: Trivial
> Fix For: 2.9
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Updated: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Tomer Gabel updated LUCENE-1670:
--------------------------------
Attachment: lucene_1670.patch
Patch for r780565
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12715098#action_12715098 ]
Tomer Gabel commented on LUCENE-1670:
-------------------------------------
Yeah, the minor typo I fixed. It's not in the diff though. Oh well, I'll get it next time...
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Assignee: Michael McCandless
> Priority: Trivial
> Fix For: 2.9
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Tomer Gabel (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12714987#action_12714987 ]
Tomer Gabel commented on LUCENE-1670:
-------------------------------------
Good comments all around, I should definitely have caught all of those. I'll post an update presently.
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Assigned: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Michael McCandless (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Michael McCandless reassigned LUCENE-1670:
------------------------------------------
Assignee: Michael McCandless
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Assignee: Michael McCandless
> Priority: Trivial
> Fix For: 2.4.2
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Michael McCandless (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12715096#action_12715096 ]
Michael McCandless commented on LUCENE-1670:
--------------------------------------------
Hmm I see that bullet too, but when I look at the patch it doesn't have the added import? Maybe something got mixed up when you attached the patch? Are there any other intended changes missing?
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Assignee: Michael McCandless
> Priority: Trivial
> Fix For: 2.9
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1670) Cosmetic JavaDoc updates
Posted by "Shai Erera (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1670?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12715047#action_12715047 ]
Shai Erera commented on LUCENE-1670:
------------------------------------
Ok I checked and if you reference an item which is not generated in the Javadocs, it appears in monospace, with no link. So I guess referencing SegmentInfo is fine. Just as a FYI, not everybody use Eclipse, and Eclipse (I think since 3.4) has the ability to update String references to class names you refactor.
This look good now. Unfortunately, I'm not a committer so I cannot take this issue any further :). Hope my review will help the committer that will choose to commit it.
> Cosmetic JavaDoc updates
> ------------------------
>
> Key: LUCENE-1670
> URL: https://issues.apache.org/jira/browse/LUCENE-1670
> Project: Lucene - Java
> Issue Type: Improvement
> Components: Javadocs
> Affects Versions: 2.4.2
> Environment: Lucene SVN (diff from r780545)
> Reporter: Tomer Gabel
> Priority: Trivial
> Fix For: 2.4.2
>
> Attachments: lucene_1670.patch
>
>
> I've taken the liberty of making a few cosmetic updates to various JavaDocs:
> * MergePolicy (minor cosmetic change)
> * LogMergePolicy (minor cosmetic change)
> * IndexWriter (major cleanup in class description, changed anchors to JavaDoc links [now works in Eclipse], no content change)
> Attached diff from SVN r780545.
> I would appreciate if whomever goes over this can let me know if my issue parameter choices were correct (yeah, blame my OCD), and if there's a more practical/convenient way to send these in, please let me know :-)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org