Ruby class documentation barely exists

[dorner]

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?

[esrauchg]

We would be happy to review PRs that add comments.

[dorner]

That's great! I started looking into this and ran into some issues with the generation of comments from C code: lsegal/yard#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.

[dorner]

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?

[dorner]

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?

[esrauchg]

Chiming in as not-a-ruby-expert, it seems like #15633 might be related?

[dorner]

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.