I like this, it's much clearer. 

It's more examples than usage though - you could start with `vcloud-query [options] queriable_type` for usage, and then put the rest under an examples heading? Add the `--filter` example as well, and then ditch the examples section further down.

I prefer the way you've written it here as well, i.e. all in one block with comments.