protocolbuffers
Ruby class documentation barely exists
What language does this apply to? Ruby
Describe the problem you are trying to solve.
Currently, languages like Golang provide full documentation on fields and methods for Protobuf objects:
- https://pkg.go.dev/github.com/golang/protobuf/proto#Message
- https://googleapis.dev/python/protobuf/latest/google/protobuf/message.html
- https://www.javadoc.io/doc/com.google.protobuf/protobuf-java/latest/com/google/protobuf/Message.html
The Ruby documentation https://www.rubydoc.info/gems/google-protobuf is extremely bare-bones and doesn't include any of the C-generated methods - there isn't even an entry for the Message class.
Describe the solution you'd like
I can definitely help with generating documentation via YARD comments. YARD allows you to make "fake" methods so it shouldn't affect the C-generated methods. There are other options of course, but that might be the one with the least lift.
Is this something that the team would be interested in accepting?
That's great! I started looking into this and ran into some issues with the generation of comments from C code: https://github.com/lsegal/yard/issues/1614
If I can't get this resolved, another option would be to create "dummy" Ruby files containing nothing but comments that YARD can key off of. The downside with this is that it would mean copying the content from the C files into the Ruby files, and having that there twice. I could try to write a script to do this automatically, though it might be a bit funky.
Question - is there a reason our current code uses call-seq statements? It seems like that would be used for rdoc, but I can't seem to run rdoc on that code and get anything meaningful out of it. Would there be an issue with removing call-seq entirely in favor of YARD comments?
I can see that the comments are already copied to the Java files... maybe it makes sense to have the "dummy" Ruby files be the source of truth for these rather than the C/Java files, and maybe just have a single-line comment indicating which Ruby class/method is being defined there?
Chiming in as not-a-ruby-expert, it seems like https://github.com/protocolbuffers/protobuf/pull/15633 might be related?
That's pretty exciting! But it accomplishes different things. RBS files generally don't have comments explaining the "why" and "how" behind methods, just the "what". It's more for IDE integration. The docs themselves should have more information and you should be able to look them up outside the context of a specific class/instance.