docs: fix/improve references chapter a little bit

docs/references.rst

@@ -2,26 +2,16 @@
 References
 **********************************************************************
 
+.. contents::
+
 .. automethod:: pygit2.Repository.listall_references
 .. automethod:: pygit2.Repository.lookup_reference
 
-Reference lookup::
+Example::
 
     >>> all_refs = repo.listall_references()
     >>> master_ref = repo.lookup_reference("refs/heads/master")
-    >>> commit = repo[master_ref.oid]
-
-Reference log::
-
-    >>> head = repo.lookup_reference('refs/heads/master')
-    >>> for entry in head.log():
-    ...     print(entry.message)
-
-Shortcuts::
-
-    >>> # These two lines are equivalent
-    >>> head = repo.head
-    >>> head = repo.lookup_reference('HEAD').resolve()
+    >>> commit = repo[master_ref.target]
 
 
 The Reference type
@@ -38,7 +28,12 @@ The Reference type
 
 
 The HEAD
---------------------
+====================
+
+Example. These two lines are equivalent::
+
+    >>> head = repo.lookup_reference('HEAD').resolve()
+    >>> head = repo.head
 
 .. autoattribute:: pygit2.Repository.head
 .. autoattribute:: pygit2.Repository.head_is_detached
@@ -46,7 +41,13 @@ The HEAD
 
 
 The reference log
---------------------
+====================
+
+Example::
+
+    >>> head = repo.lookup_reference('refs/heads/master')
+    >>> for entry in head.log():
+    ...     print(entry.message)
 
 .. autoattribute:: pygit2.RefLogEntry.oid_new
 .. autoattribute:: pygit2.RefLogEntry.oid_old

src/reference.c

@@ -195,7 +195,10 @@ Reference_resolve(Reference *self, PyObject *args)
 }
 
 
-PyDoc_STRVAR(Reference_target__doc__, "Target.");
+PyDoc_STRVAR(Reference_target__doc__,
+    "The reference target: If direct the value will be an Oid object, if it\n"
+    "is symbolic it will be an string with the full name of the target\n"
+    "reference.");
 
 PyObject *
 Reference_target__get__(Reference *self)
@@ -264,7 +267,7 @@ error:
 }
 
 
-PyDoc_STRVAR(Reference_name__doc__, "The full name of a reference.");
+PyDoc_STRVAR(Reference_name__doc__, "The full name of the reference.");
 
 PyObject *
 Reference_name__get__(Reference *self)
@@ -275,7 +278,7 @@ Reference_name__get__(Reference *self)
 
 
 PyDoc_STRVAR(Reference_type__doc__,
-  "Type (GIT_REF_OID or GIT_REF_SYMBOLIC).");
+    "Type, either GIT_REF_OID or GIT_REF_SYMBOLIC.");
 
 PyObject *
 Reference_type__get__(Reference *self)