API doc is unclear

[shyuep]

@munrojm @janosh

It is rather difficult to find examples on how to do most API queries. Getting to the API page requires multiple clicks on links and some of those links are circular.

Further, the difference between search and _search is rather subtle. For instance

mpr.materials.search(nelements=2) fails because nelements is apparently not a keyword, despite the documentation saying it is.

But mpr.materials._search(nelements=2) inexplicably works.

1. General python convention is that an underscore in front of a method name is a private function and should not be part of an exposed method API, i.e., developers have the right to modify this method at will with no regard to backwards compatibility. So the documentation really shouldn't recommend people use _search as the underlying method.
2. It is unclear why nelements does not work for search.
3. I suggest modifying _search to something else, like query, or at least, search_advanced.