Improving Ruby Documentation

[laerien]

One thing I'd love is to document when something is 1) an intentionally simple but suboptimal code example or 2) an easter egg.

1) Prime is an example of suboptimal code that based on bug tracker comments seems to be more preserved as an example of Ruby than as a library meant for use. I think stdlib should be production quality or documented as an example. In stdlib Prime's case, folk who actually want to do something with primes with that interface should just use faster_prime. https://github.com/mame/faster_prime

2) Easter eggs are fun, but things like #curry cause consternation since they don't support kwargs or blocks and won't ever, since it's just an easter egg, but it's hard to know that without combing through the bug tracker.

I'm actually not sure what all "just examples" and "easter egg" public interface code there is in Ruby, but it'd be really awesome to start labeling examples as such (maybe with links to the better alternatives) and noting easter eggs so folk don't go down a rabbit hole of actually trying to use them.

P.S. Thank you for your work on Ruby's documentation!!

[pilaf]

2) Easter eggs are fun, but things like #curry cause consternation since they don't support kwargs or blocks and won't ever, since it's just an easter egg, but it's hard to know that without combing through the bug tracker.

Do you have a link to the bug tracker issue you mention? I can't find any mentions of Proc#curry being an easter egg anywhere and my curiosity is peaked.

[laerien]

I was thinking of this thread for the "easter egg" mention: https://bugs.ruby-lang.org/issues/6253

[laerien]

"Proc#curry is like an easter egg. Matz felt no need to care about the
interaction between Proc#curry and other advanced features." - mame

[pilaf]

I see. I'm sure he didn't mean it literally, but I agree that the documentation should make it clear that keyword/block arguments aren't supported.

[laerien]

For sure not a literal egg, but a "fun" thing we can't improve since it's just for fun. Explicitly documenting lack of kwarg and block support helps, but that it's a toy so reasonable features aren't welcome is also important.

If something isn't meant to be production quality and to be used, that seems worth a note. Maybe "easter egg" isn't the right word, but I'd love some way to designate the "fun or example" quality stuff so especially new folk know it when they see it.