yardoc documentation

[ellnix]

This gem doesn't really have great documentation. While there was discussion about the wiki in #541 I think rdoc documentation in the source code would be a better solution.

• would work offline
• could be picked up by code editors
• would be easier to keep up to date (if a pr makes a change it should change the documentation as well)

[ellnix]

@brunoocasali let me know if this is a good idea or we make efforts toward keeping an up to date wiki.

I'll start work on whichever you prefer.

[ellnix]

@brunoocasali Opened #602 so we can concretely discuss whether this is the right way to go, won't work on it until you give the go ahead.

[brunoocasali]

It was a desire of the integrations team a few years ago, but we never went for it because of time; time is always a constraint when you need to choose between two things 😅.

If you want to do it, you definitely have my go!

[ellnix]

@wesharper This is something we could collaborate on, if you are interested. You should be able to generate much of this with an LLM if you are so inclined, but I'm not sure if that would actually be less work than writing it outright.

A little bit of work is already done on #602, if you are to work on this please look through that and let me know if you agree with the formatting decisions made, or if you have other suggestions.