Tor Norbye wrote:
On Oct 27, 2007, at 1:46 AM, Bill Dortch wrote:
On 10/26/07, *Charles Oliver Nutter* <[EMAIL PROTECTED]
<mailto:[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
Ah, Tor, this may be a bit tad, but about import... It's strongly
deprecated. It has bad interactions with Rake. =)
Cheers
--
Ola Bini (http://ola-bini.blogspot.com)
JRuby Core Developer
Developer, ThoughtWorks Studios (http://studios.thoughtworks.com)
Practical JRuby on Rails (http://apress.com/book/view/9781590598818)
"Yields falsehood when quined" yields falsehood when quined.
---------------------------------------------------------------------
To unsubscribe from this list please visit:
http://xircles.codehaus.org/manage_email
