Better scope prism's C API

[kddnewton]

At the moment, prism exposes a lot of structs and functions in its C API. Overall, the shape is not clearly defined. We should take a couple of steps to resolve this:

• We should have a split between our public and private header files.
• Ideally, I would love pm_node_t to be an opaque pointer. Because they are always heap-allocated, we should be able to get away with this.
• The public API should be documented here: https://ruby.github.io/prism/c/index.html. At the moment, it is clear that too much is exposed.
• Every attribute should have a defined getter macro to make it maintainable going forward, in case we need to change a name or the structure of the AST.

[Cluster444]

I'd be willing to champion this. I'm building a zig binding to prism so having a clear line in the sand on what is public would be great to have. Here's some questions about this

• Something like includes/internal for the private headers?
• Is pm_node_t the only type that needs to be an opaque pointer? What about parser/buffer and some others?
• That is definetly a lot! How are those docs generated?
• Can you give a couple of examples of what you have in mind for the getter macros?

[kddnewton]

Hey @Cluster444 — thanks for the initiative here. Unfortunately I've experimented with this and it would mostly need to be done within the CRuby codebase first in order to fully determine the impact here. That's the main consumer of the C library. Additionally we would need to check that the rust and wasm bindings aren't impacted. I also don't think we can do the opaque pointer trick I was hoping for without sacrificing on performance unfortunately. That is to say, I think this is quite a bit task, so maybe I shouldn't have left it quite as open ended as I did.

That being said, some answers to your questions:

• Yes, includes/internal is exactly what I was thinking.
• I think we should abandon the opaque pointer idea for now.
• The docs are generated using doxygen.
• I think the getter macros should go away for now until we have a better plan of attack for them.

[Cluster444]

Roger that.

It sounds like for now then making a list of what is to be public vs private would be a good starting point to clean up the public API?

[kddnewton]

Yes, and even documenting it in the API docs (i.e. inline in the code) would be super helpful.