On Oct 27, 2007, at 1:46 AM, Bill Dortch wrote:
On 10/26/07, Charles Oliver Nutter <[EMAIL PROTECTED]> wrote:
What would you folks say to moving all the javasupport .rb files
out of
the jruby.jar file and into a directory under lib?
Hmm. Those files are very closely integrated with the Java JI
implementation, and I'd be concerned about a number of things:
- the potential for users to end up with .rb files out of sync
with the Java JI code, possibly leading to phantom "bugs"
- fostering a perception that the JI interface exposed in Ruby is
in any way a stable API -- it's not, and will most certainly
change before long (I've made some changes since 1.0). Users
should be discouraged from calling its methods directly (any of the
Java or JavaUtilities methods, for example).
- along the same lines, an unsuspecting user might be tempted to
put a lot of effort into modifying / extending classes like
ArrayJavaProxy or ConcreteJavaProxy that are slated for extinction
in the near future.
I foresee nearly all of the Ruby-implemented JI code going away
before too long; when it does, it won't be practical to deprecate
it and try to preserve the old interface. It will just be gone.
Unless we want to include stern warnings to this effect in each
file, I think it's probably best not to go out our way to make
these files accessible.
-1
But users -do- need to find out about some of the modules and methods
in order to be able to actually call into Java - such as "import".
I filed an issue, 1473, to stick ":nodoc:" on anything not intended
to be used by users. A simple comment line stating something like "#
Implementation machinery, don't extend as it may soon change or
disappear" can also help - but I think ":nodoc:" would help. That
would make it trivial to run rdoc on these files to find out what the
APIs for Java integration are for any specific JRuby version. Right
now it seems to be documented via blogs or other means.
This ":nodoc:" is important for IDE usage as well because I'm now
using it to filter out stuff from code completion. Thus, classes that
are implementation artifacts marked by :nodoc: won't show up, but
other methods and modules, such as module Java and method import,
will show up.
-- Tor
