Thoughts about BaseModel methods.

[davidorme]

Caution

These are some incomplete musings that I'm parking here while I mull.
I strongly advise not reading them right now

 I've got a thought about the how the BaseModel definition and model documentation are setup.

At the moment, we have BaseModel._setup and BaseModel._update as the abstract methods. Those are private so no docstrings on those methods from actual model implementations currently appear in the documentation. That kinda means that all model description has to go in the module docstring or the class docstring, even when it might be clearer to document the method specific steps in the methods.

We can fix that in one of three ways:

1. Suck it up. I don't much like this solution as it leads to monolithic doc sections rather than docs structured by methods.
2. Document the private methods, so that _setup and _update appear for each model. I'm kinda ok with this, but if we're exposing docstrings on all of these private methods, is there actually any point in having the odd names, which leads to..
3. Make the names public so that the methods are setup and update. That's slightly odd for setup, which currently is always called by __init__ so shouldn't be called directly, but update can be run.