[DOC] improved docstrings for BaseObject (#369)

Improves the docstrings of methods in `BaseObject` by:

* ensuring proper rst formatting throughout
* cleraly explaining difference between tags and configs
* clearly explaining state and returns of tags and config objects
* making more complete explanations of input-output behaviour