$db is confusing in the docs.

When I enter the docs and see something like this:

Code:

$fields = $db->getFieldNames('table_name');

It confuses the hell out of me to figure out WHERE $db 'magically' comes from ... I see it NOWHERE in MY ResourceControllers ... and if I try to define it all hell breaks loose ...

Now, please add some understandable CONTEXT when writing docs.

Can someone please shed some light on HOW to understand the docs when trying to use it as a reference?