Repository navigation
Add @CRuby annotation linking Java code to CRuby functions - #9782
Conversation
|
@headius here is the PR to discuss the annotation proposal |
headius
left a comment
There was a problem hiding this comment.
The annotation makes sense and I think it will be a useful tool for both humans and agents porting code from CRuby to JRuby.
The tool is largely inscrutable (and quite a mess) but once comments are all converted to annotations most of this logic won't really be needed anymore. Future links will be handled by the person or agent working on that code.
It might make sense to commit only the annotation-auditing/correcting part of the tool, and it doesn't make sense to commit it here; that should also go with the conversion PR.
Basically, strip this down to just the annotation and relevant documentation and we'll iterate on the one-shot conversion in a separate PR.
@enebo What do you think? @CRuby or @CAPI or what?
Adds org.jruby.anno.CRuby (repeatable, RUNTIME, @documented) to replace "// MRI: rb_foo" comments, so the mapping can be audited by tools and used by docs and runtime tooling. Converts the MRI comments in RubyMatchData as a first use, and notes the convention in CONTRIBUTING.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
check verifies @cruby names (and files, when given) against a CRuby checkout. survey reports the comment-style references not yet converted. tool/cruby_annotations_test.rb tests both against a small fake CRuby tree. Split out of jruby#9782 for a separate PR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
headius
left a comment
There was a problem hiding this comment.
Let's go with this so we can work on doing the conversion. If we ultimately decide on a different name it will be trivial to rename the annotation them.
|
@zev @headius Someone once said the entire C codebase is the C extension API. As true as that may be I think the idea behind our comments was not about the C extension API but about C internals. And many people probably do think it is a subset of MRI internals. So I think CRuby is a better name. In the future for Java native extension authors perhaps CAPI would be reasonable for things people expect but we already have a strategy for that: https://github.com/jruby/jruby/blob/master/core/src/main/java/org/jruby/api/MRI.java. |
|
@enebo Yeah that's basically where I stand on this too. Many of the ported functions are internal and not part of the C extension API also. That MRI namespace probably should be renamed to something C extension related but I think with these CRuby annotations it may not even be needed in the future. |
I have never liked the idea of these methods preferring a dictionary annotation on the other "api" package static methods but I think we already had these....and I never added an annotation for a dictionary to be made :P Err, What I imply here is I prefer the use of org.jruby.api and being the only used entry point for native extensions. Glacially long term we may want to move our internals around and .api.Create etc can just be how we eliminate people hitting RubyArray and friends. |
|
Yeah my goal with this annotation is more for maintainers than people running extensions. Whether those maintainers are humans or agents, having a structured way of identifying the code some method was ported from will help keep it in line going forward. |
|
This is an unnecessary complication, LLM now needs to learn about annotation instead of just reading comments (which it is implicitly goot at) - so it's just an indirection. IMHO, a special thing to maintain that will go out of sync unless explicitly prompted. also, if it's for source reading for human/agent why |
|
I don't feel like the annotation is any more complex than the comment, to be honest, and now it's literally attached to the code and the classes and the methods for tools to be able to audit. How is it more complex to have a CRuby annotation versus a CRuby comment that's essentially the same thing? These references have also tended to drift over time and they are much more difficult to consistently clean up when everybody has their own way of writing the comment for it. As annotations we can have a deterministic tool that digs up the symbols and makes sure the references still make sense. |
|
Also, isn't a comment just a form of annotating code? I just see this as more formal. |
Follows the discussion in #9767 (comment). This adds an annotation that links a Java method, class or field to the CRuby C function or macro it implements, so the link can be checked by tools and used by docs, IRB, RI and language servers. The
// MRI: rb_fooand/** rb_foo */comments we have now can't do that. cc @eneboWhat's here
org.jruby.anno.CRuby:value(C name), optionalfile, optionalnote("first half" and the like). Repeatable,RUNTIME,@Documented, as discussed.RubyMatchData: the four existingMRI:comments are converted, as a first use.CONTRIBUTING.md: a short note to use@CRubyinstead of// MRI:comments.Not in this PR
tool/cruby_annotations.rb). As suggested in review, it moved to a separate PR together with the one-shot conversion of the ~1,100 remaining comments. It is on thecruby-annotation-toolbranch for now.Methodto its@CRuby(for example a manifest from the annotation processor). For now, tools find it by reflecting on the Java method behind a@JRubyMethod.Open questions
@CRubyfor now (CAPIandRubyAPIwere also mentioned). @enebo?Testing
🤖 Generated with Claude Code