Documenting weird mixins

[Michael B. Klein]

I'm at a bit of a loss as to how to document
https://github.com/microservices/pairtree/blob/master/lib/pairtree/obj.rb.

The class is a Dir descendant, but it has a whole bunch of File class
methods mixed in for convenience. Basically, all the mixed in methods
pass their parameters straight through to File, but with the partree
root/ppath prepended to all filename parameters. There are also a few
methods (entries, each, glob, and []) mixed in from Dir in similar
fashion. In this case, they pass their (prepended) args to Dir, and
alter the results to be relative to the ppath.

So much of the implementation relies on Ruby's metaprogramming that I
just can't figure out how to document it in a way that makes sense.
I'd appreciate suggestions and/or assistance.

Thanks!
Michael

[Jason Ronallo]

Since there's another pairtree implementation,[1] I wonder if we need
both? I feel like all I really need in a pairtree library is something
that gets the pieces in the basic spec right and doesn't necessarily
become some Dir/File thing. I've used orchard before because of its
simplicity, but then again it doesn't have a test named "should
roundtrip hardcore Unicode".

Jason

[1] https://github.com/cdlib/orchard

[Michael Giarlo]

I'm ambivalent on whether or not the new pairtree library (forked from cbeer's, right?) should be retired in light of already having the orchard library.

But one possible outcome would be to let orchard handle the basics (translations between identifiers and paths) and build this other pairtree library on top of it, providing advanced store-like functionality such as in Ben O'Steen's python-based pairtree library [1].  That way we don't reproduce basic functionality, and have access to advanced pairtree functionality in Ruby for those of us coming from Python.  

-Mike

 1. https://github.com/benosteen/pairtree