Fixup documentation

* Remove Doxygen markup;
* Update OMSP specification link;
* Fix non-meaningful whitespace errors.

Signed-off-by: Olivier Mehani <olivier.mehani@nicta.com.au>
Be more resilient in parsing Collection URI

Channel::_connect only expects fully-qualified collection URIs, with
scheme, and port when relevant. The OML4R class now has a qualify_uri
method which takes a possibly under-qualified URI, and returns a
fully-qualified collection URI suitable for Channel::_connect.

Additionally, the info message about the collection URI is moved upward
so the user knows what OML4R is trying to connect to before it might
fail cryptically.

Also, document Channel::_connect and OML4R::qualify_uri with Yard
markup.

fixes: #935

Signed-off-by: Olivier Mehani <olivier.mehani@nicta.com.au>