diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py
index 6163734bd..64bf73d75 100644
--- a/docs/gen_reference_doc.py
+++ b/docs/gen_reference_doc.py
@@ -49,6 +49,7 @@ symbols = \
 
 static_links = \
 {
+	".. _`BEP 3`: http://bittorrent.org/beps/bep_0003.html",
 	".. _`BEP 17`: http://bittorrent.org/beps/bep_0017.html",
 	".. _`BEP 19`: http://bittorrent.org/beps/bep_0019.html"
 }
@@ -814,8 +815,20 @@ for cat in categories:
 	functions = categories[cat]['functions']
 	enums = categories[cat]['enums']
 
+	out.write('%s\n' % heading(cat, '='))
+
+	out.write('''
+:Author: Arvid Norberg, arvid@rasterbar.com
+:Version: 1.0.0
+
+.. contents:: Table of contents
+  :depth: 2
+  :backlinks: none
+
+''')
+
 	if 'overview' in categories[cat]:
-		out.write('%s\n%s\n' % (heading(cat, '='), categories[cat]['overview']))
+		out.write('%s\n' % categories[cat]['overview'])
 
 	for c in classes:
 
diff --git a/include/libtorrent/bencode.hpp b/include/libtorrent/bencode.hpp
index 715a2cde4..d89378b6d 100644
--- a/include/libtorrent/bencode.hpp
+++ b/include/libtorrent/bencode.hpp
@@ -36,32 +36,46 @@ POSSIBILITY OF SUCH DAMAGE.
 
 
 
-/*
- * This file declares the following functions:
- *
- *----------------------------------
- * template<class OutIt>
- * void libtorrent::bencode(OutIt out, const libtorrent::entry& e);
- *
- * Encodes a message entry with bencoding into the output
- * iterator given. The bencoding is described in the BitTorrent
- * protocol description document OutIt must be an OutputIterator
- * of type char. This may throw libtorrent::invalid_encoding if
- * the entry contains invalid nodes (undefined_t for example).
- *
- *----------------------------------
- * template<class InIt>
- * libtorrent::entry libtorrent::bdecode(InIt start, InIt end);
- *
- * Decodes the buffer given by the start and end iterators
- * and returns the decoded entry. InIt must be an InputIterator
- * of type char. May throw libtorrent::invalid_encoding if
- * the string is not correctly bencoded.
- *
- */
-
-
-
+// OVERVIEW
+// 
+// Bencoding is a common representation in bittorrent used for
+// for dictionary, list, int and string hierarchies. It's used
+// to encode .torrent files and some messages in the network
+// protocol. libtorrent also uses it to store settings, resume
+// data and other state between sessions.
+//
+// Strings in bencoded structures are not necessarily representing
+// text. Strings are raw byte buffers of a certain length. If a
+// string is meant to be interpreted as text, it is required to
+// be UTF-8 encoded. See `BEP 3`_.
+//
+// There are two mechanims to *decode* bencoded buffers in libtorrent.
+//
+// The most flexible one is bdecode(), which returns a structure
+// represented by entry. When a buffer is decoded with this function,
+// it can be discarded. The entry does not contain any references back
+// to it. This means that bdecode() actually copies all the data out
+// of the buffer and into its own hierarchy. This makes this
+// function potentially expensive, if you're parsing large amounts
+// of data.
+//
+// Another consideration is that bdecode() is a recursive parser.
+// For this reason, in order to avoid DoS attacks by triggering
+// a stack overflow, there is a recursion limit. This limit is
+// a sanity check to make sure it doesn't run the risk of
+// busting the stack.
+//
+// The second mechanism is lazy_bdecode(), which returns a
+// bencoded structure represented by lazy_entry. This function
+// builds a tree that points back into the original buffer.
+// The returned lazy_entry will not be valid once the buffer
+// it was parsed out of is discarded.
+//
+// Not only is this function more efficient because of less
+// memory allocation and data copy, the parser is also not
+// recursive, which means it probably performs a little bit
+// better and can have a higher recursion limit on the structures
+// it's parsing.
 
 #include <stdlib.h>
 #include <string>
@@ -87,6 +101,8 @@ POSSIBILITY OF SUCH DAMAGE.
 namespace libtorrent
 {
 
+	// thrown by bdecode() if the provided bencoded buffer does not contain
+	// valid encoding.
 	struct TORRENT_EXPORT invalid_encoding: std::exception
 	{
 		virtual const char* what() const throw() { return "invalid bencoding"; }
diff --git a/include/libtorrent/create_torrent.hpp b/include/libtorrent/create_torrent.hpp
index 9710e8839..5f33c2fb9 100644
--- a/include/libtorrent/create_torrent.hpp
+++ b/include/libtorrent/create_torrent.hpp
@@ -108,6 +108,7 @@ namespace libtorrent
 	// .torrent file using bencode().
 	struct TORRENT_EXPORT create_torrent
 	{
+		// flags for create_torrent::create_torrent().
 		enum flags_t
 		{
 			// This will insert pad files to align the files to piece boundaries, for
diff --git a/include/libtorrent/entry.hpp b/include/libtorrent/entry.hpp
index cfc1316ff..c80ba46af 100644
--- a/include/libtorrent/entry.hpp
+++ b/include/libtorrent/entry.hpp
@@ -78,6 +78,9 @@ namespace libtorrent
 {
 	struct lazy_entry;
 
+	// thrown by any accessor function of entry if the accessor
+	// function requires a type different than the actual type
+	// of the entry object.
 	struct TORRENT_EXPORT type_error: std::runtime_error
 	{
 		type_error(const char* error): std::runtime_error(error) {}