diff --git a/elasticsearch/client/__init__.py b/elasticsearch/client/__init__.py
index 5c854789..3b09c8a6 100644
--- a/elasticsearch/client/__init__.py
+++ b/elasticsearch/client/__init__.py
@@ -64,8 +64,8 @@ class Elasticsearch(object):
     Elasticsearch low-level client. Provides a straightforward mapping from
     Python to ES REST endpoints.
 
-    The instance has attributes `cat`, `cluster`, `indices`, `nodes` and
-    `snapshot` that provide access to instances of
+    The instance has attributes ``cat``, ``cluster``, ``indices``, ``nodes``
+    and ``snapshot`` that provide access to instances of
     :class:`~elasticsearch.client.CatClient`,
     :class:`~elasticsearch.client.ClusterClient`,
     :class:`~elasticsearch.client.IndicesClient`,
@@ -100,7 +100,7 @@ class Elasticsearch(object):
     specify those::
 
         # connect to localhost directly and another node using SSL on port 443
-        # and an url_prefix
+        # and an url_prefix. Note that ``port`` needs to be an int.
         es = Elasticsearch([
             {'host': 'localhost'},
             {'host': 'othernode', 'port': 443, 'url_prefix': 'es', 'use_ssl': True},
diff --git a/elasticsearch/connection/base.py b/elasticsearch/connection/base.py
index 0bc6192f..aa2ce332 100644
--- a/elasticsearch/connection/base.py
+++ b/elasticsearch/connection/base.py
@@ -28,9 +28,9 @@ class Connection(object):
     def __init__(self, host='localhost', port=9200, url_prefix='', timeout=10, **kwargs):
         """
         :arg host: hostname of the node (default: localhost)
-        :arg port: port to use (default: 9200)
+        :arg port: port to use (integer, default: 9200)
         :arg url_prefix: optional url prefix for elasticsearch
-        :arg timeout: default timeout in seconds (default: 10)
+        :arg timeout: default timeout in seconds (float, default: 10)
         """
         self.host = '%s://%s:%s' % (self.transport_schema, host, port)
         if url_prefix: