Documented API calls' return format.
Fixed some spacing.
Improve API call descriptions

Added more explicit descriptions about API calls that return JSON objects.
Fixed some ambiguous wording.
Fixed some icky spacing.
Fix vncport value in example

Change from string to int.  Change to a realistic value.
Clarified some documentation

Documented the scenarios that the vncport field in show_headnode can be None
Merge pull request #310 from ryabouza/rest-api-calls-doc

Documented API calls' return format.