I can see how documenting and ensuring consistency might be more difficult with this alternate method. For TokenOperator, in practice, I would always lock down the API with wrapper functions as noted at https://github.com/baldwindavid/token_operator#making-it-our-own
Thus, you end up only using maybe_filter, maybe_include, maybe_order_by, etc. and those only respond to the pre-defined atoms of :filter, :include, :order_by, etc.
You can interact with TokenOperator directly, but I would usually suggest writing a simple wrapper around it. It is pretty low-level; so much so that it’s a little hard to explain without writing a higher-level abstraction on top of it as an example. Things like QueryBuilder don’t suffer from that as it is immediately obvious how to use it.
I don’t have a great answer for locking down / documenting the API for this alternate method. Maybe what @chrisjowen mentioned of putting them in a XXX.Queries module helps. It hasn’t been a problem for me yet. I break my contexts into sub-contexts (ex. MyApp.Calendar.Reservations), so they are usually not so large that I need to split them up further.
