From 31659fa673ac4921fca58aad66298b63a196bb73 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=2E=20David=20Ib=C3=A1=C3=B1ez?= <jdavid.ibp@gmail.com>
Date: Sun, 28 Apr 2013 11:16:31 +0200
Subject: [PATCH] docs: fix/improve references chapter a little bit

---
 docs/references.rst | 33 +++++++++++++++++----------------
 src/reference.c     |  9 ++++++---
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/docs/references.rst b/docs/references.rst
index 2ea5731..943c367 100644
--- a/docs/references.rst
+++ b/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
diff --git a/src/reference.c b/src/reference.c
index 25b40cf..f4478db 100644
--- a/src/reference.c
+++ b/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)