WIP - Various improvements to the API documentation

I'm currently writing an API client for the gitlab API and in the process found some points where the documentation for the API can be improved. This is my pull-request of running changes, more might follow. I'll update the PR and will comment when I'm through but I wanted the changes to be available for discussion as early as possible.