Currently http/oauth2 libraries are using the new format suggested by Xcode 6.x for API documentation. More details about this format can be found on the great article from nshipster

Once 'jazzy' or 'appledoc' provide support for generating html from this format we will opt to use it:

See the issues in project respective 'issues' page:
jazzy:
https://github.com/realm/jazzy/issues/34

appledoc:
https://github.com/tomaz/appledoc/issues/460