Improve Documentation

[ahx]

There are quite a few ways to use this library and options to configure. I need some help to document the public APIs.

[richardboehme]

Hey! Maybe I could spare some time to add documentation for some APIs. Do you already have an idea in which way they should be documented? What do you think about adding some kind of type signatures, e.g. using RBS Inline, for public API documentation?

[ahx]

Hi. I have not used rbs-inline successfully so far, but I am very interested to see it working. Until now I have used yardoc to have some documentation on rubydoc.info.
So yes, adding more documentation via yardoc or rbs-inline would be great.

Another thing I am interested in is improving the visible class structure. One problem with the default documentation on rubydoc.info is that it just lists every minor class, which is very noisy. I have hidden some classes with "@visibility private", but it all still looks a bit messy, doesn't it?

[richardboehme]

Oh I should have looked into the already existing rubydoc stuff 🤦

So yes, adding more documentation via yardoc or rbs-inline would be great.

I guess if you already use yard it makes sense to stick to it, no? I like RBS Inline but tbh it probably won't help users too much because there is no documentation generator (I think) and the LSP integration will probably only work if they already use the Sorbet LSP or if the gem ships RBS signatures and they use the Steep LSP.

I have hidden some classes with "@visibility private", but it all still looks a bit messy, doesn't it?

As long as all classes available are public API I do not know how much you can do about it without changing the structure of the classes itself? I think people only use the class list on rubydoc if they know what they are looking for (e.g. I want to lookup how OpenapiFirst::Test.setup works). The actual information how things work are probably best places into the README or in the concrete class with a reference to it in the README.

[ahx]

[…] without changing the structure of the classes itself?

Yeah, I guess that’s what I wanted to imply that I would like to work on, but that probably does not fit into this issue.

Picking some central things like Test.setup or ValidatedRequest or the like and adding more information to those sounds like a good plan. Thanks for the reply.