add hints to api_samples documentation

Based on my own experience and questions I recently answered in
the openstack-nova channel, these hints could help developers.

Change-Id: Id7350f1a6a834b0de8456fdc28c2db890f2971de
Merge "add hints to api_samples documentation"