Re: FieldCache documentation/exposure

[Doron Cohen <DO...@il.ibm.com>]

>
> : Guess there are no reservations on the subject; I'll enhance the
> : documentation of this mechanism.
>
> Sorry ... i'm a little behind on my mail ...

I think I know what you mean...

> I wouldn't go advertising it *too* heavily ... i think directly using
> FieldCache is definitely an "Expert" level thing, and we tend to keep the
> documentation on Expert level stuff minimal with the assumption that
> people diging in to that level will familiarize themselves with the code
a
> bit not just read the javadocs.

That's the "tendency" I thought I am identifying, but wasn't sure.

> that said .. i think it's pretty hard ot have too much javadocs ...
> inhancing hte ____ javadocs to explain what ____ is and how it can be
used
> is always good (wether the blank is field in with FieldCache or the name
of
> any other class) but i don't think we need to promote it heavily from the
> top package level javadocs where it might confuse people looking for
basic
> info on the simple aspects of the API.

Sounds fair to me - so I'll just javadoc the class/interface - will do it
in an issue/patch, so any over exposure can be reviewed before committing.

Guess suggesting to use this in user-list replies would be considered "over
advertising", but too late at least for
http://www.nabble.com/Best-way-to-returning-hits-after-search--tf3304485.html



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

Re: FieldCache documentation/exposure

[Chris Hostetter <ho...@fucit.org>]

: Guess suggesting to use this in user-list replies would be considered "over
: advertising", but too late at least for
: http://www.nabble.com/Best-way-to-returning-hits-after-search--tf3304485.html

I think the good baseline is to compare it with HitCollector ... it's hte
kind of thing that needs to be well documented, and if a user asks a
question about doing something complex, or more efficiently then the
simple API alows we should certinaly point out that they exist -- as long
as we're clear that using them is non-trivial.

my main point about not advertising was that we shouldn't treat FieldCache
a a "First class class" on package level docs or tutorials the way we do
with Analyzers, IndexSearchers, IndexWriters, Documents, Queries, and
Filters, etc...

http://lucene.apache.org/java/docs/api/overview-summary.html#overview_description
http://lucene.apache.org/java/docs/api/org/apache/lucene/search/package-summary.html#package_description


-Hoss


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