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 [EMAIL PROTECTED] 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:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
