lucene-java-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua O'Madadhain <jmad...@ics.uci.edu>
Subject Re: CachedSearcher
Date Tue, 16 Jul 2002 18:10:21 GMT
On Tue, 16 Jul 2002, Doug Cutting wrote:

> Hang Li wrote:
> > Why there are so many final and package-protected methods?
> 
> The package private stuff was motivated by Javadoc.  When I wrote
> Lucene I wanted the Javadoc to make it easy to use.  Thus I did not
> want the Javadoc cluttered with lots of methods that 99% of users did
> not need to know about.
> 
> So a problem is how to distinguish methods that are meant for end
> users from those that only may rarely be needed by an expert
> developer.  Perhaps we could establish a Javadoc convention for those
> methods that most users don't need to know about.  For example, their
> documentation could begin "Expert:" or something.  What do folks think
> of that?

I think that this is a good idea, which perhaps ought to be combined with
a note on the top level of the documentation which would read something
like "Methods marked in the documentation with 'Expert' should only be
used by experienced users of Lucene; /caveat coder/."
 
> Also, many package private methods really are internal methods that
> are not designed to be called outside of the implementation.  Trying
> to override them probably won't work.  

Certainly things like this should be left (package) private.  

> When stuff that is tricky to use is documented and easy to use, folks
> will use it, it won't work, and they'll complain, wasting everyone's
> time.  So we must be careful about what is made public.  I would
> rather err on the side of exposing less than more--folks who know what
> they're doing can always add code into a lucene package.  It's not
> ideal, but it works.

This seems reasonable enough for most purposes.  I do wonder, though,
whether there's a "gotcha" that can arise as an unexpected side effect of
including a file in a package (for this purpose) that otherwise wouldn't
need to be included.  (I don't use packages much myself; can a piece of
code be part of more than one package?)  If nothing else, such inclusion
might be somewhat mysterious to later maintainers of that code.  This kind
of modification might also make it more difficult for people to get Lucene
contributions from more than one source to work together.

Regards,

Joshua O'Madadhain

 jmadden@ics.uci.edu...Obscurium Per Obscurius...www.ics.uci.edu/~jmadden
  Joshua O'Madadhain: Information Scientist, Musician, Philosopher-At-Tall
 It's that moment of dawning comprehension that I live for--Bill Watterson
My opinions are too rational and insightful to be those of any organization.








--
To unsubscribe, e-mail:   <mailto:lucene-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-user-help@jakarta.apache.org>


Mime
View raw message