Tor Norbye wrote:
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".
Tor has a good point here...
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.
We need to add :nodoc: everywhere that we expect there's an "internal"
API for JavaSupport.
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.
How about a compromise, gents? Some of us don't like having javasupport
files exposed that will eventually go away. Others of us want to have
.rb files in the same place so they're obvious and accessible.
Perhaps the public APIs of javasupport should be bundled into a few
specific files and moved out of the jar, while private APIs (like those
that may go away) remain inside the jar?
This would fit with the typical .rb/extension pair in Ruby, where a .rb
file exposes some public utility APIs based upon the interface
implemented by an extension. The only difference here is that the
extension itself (java support) is a mix of Ruby and Java code too. So
we'll take all the code that would represent the "extension" portion of
JavaSupport--the bits that we'd eventually want to be pure Java and that
implement the "heavy lifting" of Java integration--and keep those inside
the JAR. The "utility" portions, like the incorporation of
java/javax/etc methods into Kernel and the (possibly deprecated)
"import" enhancement to include_class, would go in the public API.
Reasonable?
Also...on the "import" deprecation issue: we kinda made our bed in 1.0
by including "import", and we can't really deprecate it on the 1.0 line.
But we could deprecate it in 1.1 and provide an alternative. I'd feel
better about that than saying it's deprecated across the board.
- Charlie
---------------------------------------------------------------------
To unsubscribe from this list please visit:
http://xircles.codehaus.org/manage_email
