automatically generate links in reference documentation for symbols (classes, enums, enum values, functions and member functions)

docs/gen_reference_doc.py

@@ -158,7 +158,7 @@ def parse_function(lno, lines, filename):
 
 				lno = consume_block(lno - 1, lines)
 				signature += ';'
-			return [{ 'file': filename[11:], 'signatures': set([ signature ]), 'names': set([ signature.split('(')[0].split(' ')[-1].strip()])}, lno]
+			return [{ 'file': filename[11:], 'signatures': set([ signature ]), 'names': set([ signature.split('(')[0].split(' ')[-1].strip() + '()'])}, lno]
 	if len(signature) > 0:
 		print '\x1b[31mFAILED TO PARSE FUNCTION\x1b[0m %s\nline: %d\nfile: %s' % (signature, lno, filename)
 	return [None, lno]
@@ -510,6 +510,13 @@ for filename in files:
 		context = ''
 	h.close()
 
+# ====================================================================
+#
+#                               RENDER PART
+#
+# ====================================================================
+
+
 if dump:
 
 	if verbose: print '\n===============================\n'
@@ -554,8 +561,17 @@ for c in classes:
 	if c['file'] in overviews:
 		categories[cat]['overview'] = overviews[c['file']]
 
+	filename = categories[cat]['filename'].replace('.rst', '.html') + '#'
 	categories[cat]['classes'].append(c)
-	symbols[c['name']] = categories[cat]['filename'].replace('.rst', '.html') + '#' + c['name']
+	symbols[c['name']] = filename + c['name']
+	for f in c['fun']:
+		for n in f['names']:
+			symbols[n] = filename + n
+
+	for e in c['enums']:
+		symbols[e['name']] = filename + e['name']
+		for v in e['values']:
+			symbols[v['name']] = filename + v['name']
 
 for f in functions:
 	cat = categorize_symbol(first_item(f['names']), f['file'])
@@ -578,6 +594,39 @@ for e in enums:
 
 def print_declared_in(out, o):
 	out.write('Declared in "%s"\n\n' % print_link(o['file'], '../include/%s' % o['file']))
+	print >>out, dump_link_targets()
+
+# returns RST marked up string
+def linkify_symbols(string):
+	lines = string.split('\n')
+	abort = False
+	ret = []
+	for l in lines:
+		if l.endswith('::'):
+			abort = True
+		if abort:
+			ret.append(l)
+			continue
+		words = l.split(' ')
+		for i in range(len(words)):
+			# it's important to preserve leading
+			# tabs, since that's relevant for
+			# rst markup
+			leading_tabs = 0
+			while leading_tabs < len(words[i]) and words[i][leading_tabs] == '\t':
+				leading_tabs += 1
+
+			# preserve commas and dots at the end
+			w = words[i].strip()
+			trailing = ''
+			if len(w) > 0 and (w[-1] == '.' or w[-1] == ','):
+				trailing = w[-1]
+				w = w[:-1]
+			
+			if w in symbols:
+				words[i] = (leading_tabs * '\t') + print_link(words[i].strip(), symbols[w]) + trailing
+		ret.append(' '.join(words))
+	return '\n'.join(ret)
 
 link_targets = []
 
@@ -597,6 +646,38 @@ def dump_link_targets():
 def heading(string, c):
 	return '\n' + string + '\n' + (c * len(string)) + '\n'
 
+def render_enums(out, enums):
+	for e in enums:
+		print >>out, '.. raw:: html\n'
+		print >>out, '\t<a name="%s"></a>' % e['name']
+		print >>out, ''
+		print >>out, heading('enum %s' % e['name'], '.')
+		width = [len('name'), len('value'), len('description')]
+
+		for i in range(len(e['values'])):
+			e['values'][i]['desc'] = linkify_symbols(e['values'][i]['desc'])
+
+		for v in e['values']:
+			width[0] = max(width[0], len(v['name']))
+			width[1] = max(width[1], len(v['val']))
+			for d in v['desc'].split('\n'):
+				width[2] = max(width[2], len(d))
+
+		print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
+		print >>out, '| ' + 'name'.ljust(width[0]) + ' | '  + 'value'.ljust(width[1]) + ' | ' + 'description'.ljust(width[2]) + ' |'
+		print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+=' + ('=' * width[2]) + '=+'
+		for v in e['values']:
+			d = v['desc'].split('\n')
+			if len(d) == 0: d = ['']
+			print >>out, '| ' + v['name'].ljust(width[0]) + ' | '  + v['val'].ljust(width[1]) + ' | ' + d[0].ljust(width[2]) + ' |'
+			for s in d[1:]:
+				print >>out, '| ' + (' ' * width[0]) + ' | '  + (' ' * width[1]) + ' | ' + s.ljust(width[2]) + ' |'
+			print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
+		print >>out, ''
+
+		print >>out, dump_link_targets()
+
+
 out = open('reference.rst', 'w+')
 out.write('''==================================
 libtorrent reference documentation
@@ -616,7 +697,7 @@ for cat in categories:
 		print >>out, '| ' + print_link(c['name'], symbols[c['name']])
 	for f in categories[cat]['functions']:
 		for n in f['names']:
-			print >>out, '| ' + print_link(n + '()', symbols[n])
+			print >>out, '| ' + print_link(n, symbols[n])
 	for e in categories[cat]['enums']:
 		print >>out, '| ' + print_link(e['name'], symbols[e['name']])
 	print >>out, ''
@@ -650,7 +731,11 @@ for cat in categories:
 
 		out.write('%s\n' % heading(c['name'], '-'))
 		print_declared_in(out, c)
-		out.write('%s\n\n.. parsed-literal::\n\t' % c['desc'])
+		c['desc'] = linkify_symbols(c['desc'])
+		out.write('%s\n' % c['desc'])
+		print >>out, dump_link_targets()
+
+		print >>out,'\n.. parsed-literal::\n\t'
 
 		block = '\n%s\n{\n' % c['decl']
 		for f in c['fun']:
@@ -687,7 +772,7 @@ for cat in categories:
 				print >>out, '\t<a name="%s"></a>' % n
 			print >>out, ''
 			for n in f['names']:
-				title += '%s() ' % n
+				title += '%s ' % n
 			print >>out, heading(title.strip(), '.')
 
 			block = '.. parsed-literal::\n\n'
@@ -695,31 +780,12 @@ for cat in categories:
 			for s in f['signatures']:
 				block += highlight_signature(s.replace('\n', '\n   ')) + '\n'
 			print >>out, '%s\n' % block.replace('\n', '\n\t')
+			f['desc'] = linkify_symbols(f['desc'])
 			print >>out, '%s' % f['desc']
+	
+			print >>out, dump_link_targets()
 
-		for e in c['enums']:
+		render_enums(out, c['enums'])
-			print >>out, '.. raw:: html\n'
-			print >>out, '\t<a name="%s"></a>' % e['name']
-			print >>out, ''
-			print >>out, heading('enum %s' % e['name'], '.')
-			width = [len('name'), len('value'), len('description')]
-			for v in e['values']:
-				width[0] = max(width[0], len(v['name']))
-				width[1] = max(width[1], len(v['val']))
-				for d in v['desc'].split('\n'):
-					width[2] = max(width[2], len(d))
-
-			print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
-			print >>out, '| ' + 'name'.ljust(width[0]) + ' | '  + 'value'.ljust(width[1]) + ' | ' + 'description'.ljust(width[2]) + ' |'
-			print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+=' + ('=' * width[2]) + '=+'
-			for v in e['values']:
-				d = v['desc'].split('\n')
-				if len(d) == 0: d = ['']
-				print >>out, '| ' + v['name'].ljust(width[0]) + ' | '  + v['val'].ljust(width[1]) + ' | ' + d[0].ljust(width[2]) + ' |'
-				for s in d[1:]:
-					print >>out, '| ' + (' ' * width[0]) + ' | '  + (' ' * width[1]) + ' | ' + s.ljust(width[2]) + ' |'
-				print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
-			print >>out, ''
 
 		for f in c['fields']:
 			if f['desc'] == '': continue
@@ -732,8 +798,11 @@ for cat in categories:
 			for n in f['names']:
 				print >>out, '%s ' % n,
 			print >>out, ''
+			f['desc'] = linkify_symbols(f['desc'])
 			print >>out, '\t%s' % f['desc'].replace('\n', '\n\t')
 
+			print >>out, dump_link_targets()
+
 
 	for f in functions:
 		h = ''
@@ -742,7 +811,7 @@ for cat in categories:
 			print >>out, '\t<a name="%s"></a>' % n
 		print >>out, ''
 		for n in f['names']:
-			h += '%s() ' % n
+			h += '%s ' % n
 		print >>out, heading(h, '.')
 		print_declared_in(out, f)
 
@@ -751,31 +820,11 @@ for cat in categories:
 			block += highlight_signature(s) + '\n'
 
 		print >>out, '%s\n' % block.replace('\n', '\n\t')
-		print >>out, f['desc']
+		print >>out, linkify_symbols(f['desc'])
 
-	for e in enums:
+		print >>out, dump_link_targets()
-		print >>out, '.. raw:: html\n'
+	
-		print >>out, '\t<a name="%s"></a>' % e['name']
+	render_enums(out, enums)
-		print >>out, ''
-		print >>out, heading('enum %s' % e['name'], '.')
-		width = [len('name'), len('value'), len('description')]
-		for v in e['values']:
-			width[0] = max(width[0], len(v['name']))
-			width[1] = max(width[1], len(v['val']))
-			for d in v['desc'].split('\n'):
-				width[2] = max(width[2], len(d))
-
-		print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
-		print >>out, '| ' + 'name'.ljust(width[0]) + ' | '  + 'value'.ljust(width[1]) + ' | ' + 'description'.ljust(width[2]) + ' |'
-		print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+=' + ('=' * width[2]) + '=+'
-		for v in e['values']:
-			d = v['desc'].split('\n')
-			if len(d) == 0: d = ['']
-			print >>out, '| ' + v['name'].ljust(width[0]) + ' | '  + v['val'].ljust(width[1]) + ' | ' + d[0].ljust(width[2]) + ' |'
-			for s in d[1:]:
-				print >>out, '| ' + (' ' * width[0]) + ' | '  + (' ' * width[1]) + ' | ' + s.ljust(width[2]) + ' |'
-			print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
-		print >>out, ''
 
 	print >>out, dump_link_targets()
 

docs/makefile

@@ -2,6 +2,22 @@
 
 WEB_PATH = ~/Documents/rasterbar/web/products/libtorrent
 
+REFERENCE_TARGETS = \
+	reference \
+	reference-Core \
+	reference-String \
+	reference-Plugins \
+	reference-Create_Torrents \
+	reference-Error_Codes \
+	reference-Time \
+	reference-Storage \
+	reference-Custom_Storage \
+	reference-Utility \
+	reference-Bencoding \
+	reference-Alerts \
+	reference-RSS \
+	reference-Filter
+
 TARGETS = index \
 	udp_tracker_protocol \
 	dht_rss \
@@ -23,20 +39,7 @@ TARGETS = index \
 	utp \
 	tuning \
 	hacking \
-	reference \
+	$(REFERENCE_TARGETS)
-	reference-Core \
-	reference-String \
-	reference-Plugins \
-	reference-Create_Torrents \
-	reference-Error_Codes \
-	reference-Time \
-	reference-Storage \
-	reference-Custom_Storage \
-	reference-Utility \
-	reference-Bencoding \
-	reference-Alerts \
-	reference-RSS \
-	reference-Filter
 
 FIGURES = read_disk_buffers write_disk_buffers troubleshooting
 
@@ -51,7 +54,7 @@ all: html
 todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp
 	python gen_todo.py
 
-reference.rst reference-Create_Torrents.rst reference-Error_Codes.rst reference-Plugins.rst reference-Core.rst reference-String.rst reference-Storage.rst:gen_reference_doc.py ../include/libtorrent/*.hpp
+$(REFERENCE_TARGETS:=.rst):gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp
 	python gen_reference_doc.py
 
 %.epub:%.rst

include/libtorrent/add_torrent_params.hpp

@@ -244,7 +244,7 @@ namespace libtorrent
 
 		// The optional parameter, ``resume_data`` can be given if up to date fast-resume data
 		// is available. The fast-resume data can be acquired from a running torrent by calling
-		// `save_resume_data()`_ on `torrent_handle`_. See `fast resume`_. The ``vector`` that is
+		// save_resume_data() on `torrent_handle`_. See `fast resume`_. The ``vector`` that is
 		// passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
 		std::vector<char> resume_data;
 
@@ -254,8 +254,8 @@ namespace libtorrent
 		// can be used to customize how the data is stored. The default
 		// storage will simply write the data to the files it belongs to, but it could be
 		// overridden to save everything to a single file at a specific location or encrypt the
-		// content on disk for instance. For more information about the ``storage_interface``
+		// content on disk for instance. For more information about the storage_interface
-		// that needs to be implemented for a custom storage, see `storage_interface`_.
+		// that needs to be implemented for a custom storage, see storage_interface.
 		storage_constructor_type storage;
 
 		// The ``userdata`` parameter is optional and will be passed on to the extension
@@ -281,7 +281,7 @@ namespace libtorrent
 		// true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used
 		// which is later updated once the .torrent file has been downloaded.
 		// 
-		// Once the info-hash change happens, a torrent_update_alert_ is posted.
+		// Once the info-hash change happens, a torrent_update_alert is posted.
 		std::string url;
 
 		// if ``uuid`` is specified, it is used to find duplicates. If another torrent is already

include/libtorrent/entry.hpp

@@ -130,7 +130,7 @@ namespace libtorrent
 
 		// The ``integer()``, ``string()``, ``list()`` and ``dict()`` functions
 		// are accessors that return the respective type. If the ``entry`` object isn't of the
-		// type you request, the accessor will throw libtorrent_exception_ (which derives from
+		// type you request, the accessor will throw libtorrent_exception (which derives from
 		// ``std::runtime_error``). You can ask an ``entry`` for its type through the
 		// ``type()`` function.
 		// 
@@ -167,7 +167,7 @@ namespace libtorrent
 		// 	}
 		// 
 		// 
-		// To make it easier to extract information from a torrent file, the class torrent_info_
+		// To make it easier to extract information from a torrent file, the class torrent_info
 		// exists.
 		integer_type& integer();
 		const integer_type& integer() const;

include/libtorrent/rss.hpp

@@ -83,16 +83,16 @@ namespace libtorrent
 
 		// By default ``auto_download`` is true, which means all torrents in
 		// the feed will be downloaded. Set this to false in order to manually
-		// add torrents to the session. You may react to the rss_alert_ when
+		// add torrents to the session. You may react to the rss_alert when
 		// a feed has been updated to poll it for the new items in the feed
 		// when adding torrents manually. When torrents are added automatically,
-		// an add_torrent_alert_ is posted which includes the torrent handle
+		// an add_torrent_alert is posted which includes the torrent handle
 		// as well as the error code if it failed to be added. You may also call
 		// ``session::get_torrents()`` to get the handles to the new torrents.
 		bool auto_download;
 
 		// ``auto_map_handles`` defaults to true and determines whether or
-		// not to set the ``handle`` field in the ``feed_item``, returned
+		// not to set the ``handle`` field in the feed_item, returned
 		// as the feed status. If auto-download is enabled, this setting
 		// is ignored. If auto-download is not set, setting this to false
 		// will save one pass through all the feed items trying to find
@@ -110,7 +110,7 @@ namespace libtorrent
 		// This object is used as a template for adding torrents from feeds,
 		// but some torrent specific fields will be overridden by the
 		// individual torrent being added. For more information on the
-		// ``add_torrent_params``, see `async_add_torrent() add_torrent()`_.
+		// add_torrent_params, see async_add_torrent() and add_torrent().
 		add_torrent_params add_args;
 	};
 

include/libtorrent/session.hpp

@@ -124,7 +124,7 @@ namespace libtorrent
 		// If the fingerprint in the first overload is omited, the client will get a default
 		// fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
 		// used in the peer-id to identify the client and the client's version. For more details see the
-		// fingerprint_ class. The constructor that only takes a fingerprint will not open a
+		// fingerprint class. The constructor that only takes a fingerprint will not open a
 		// listen port for the session, to get it running you'll have to call ``session::listen_on()``.
 		// The other constructor, that takes a port range and an interface as well as the fingerprint
 		// will automatically try to listen on a port on the given interface. For more information about
@@ -196,8 +196,8 @@ namespace libtorrent
 		// settings. ``save_state`` writes all keys to the ``entry`` that's passed in, which needs to
 		// either not be initialized, or initialized as a dictionary.
 		// 
-		// ``load_state`` expects a ``lazy_entry`` which can be built from a bencoded buffer with
+		// ``load_state`` expects a lazy_entry which can be built from a bencoded buffer with
-		// `lazy_bdecode()`_.
+		// lazy_bdecode().
 		// 
 		// The ``flags`` arguments passed in to ``save_state`` can be used to filter which parts
 		// of the session state to save. By default, all state is saved (except for the individual
@@ -210,7 +210,7 @@ namespace libtorrent
 		// 	with lots of torrents. If you're concerned about performance, consider
 		// 	using ``post_torrent_updates()`` instead.
 		// 
-		// ``get_torrent_status`` returns a vector of the ``torrent_status`` for every
+		// ``get_torrent_status`` returns a vector of the torrent_status for every
 		// torrent which satisfies ``pred``, which is a predicate function which determines
 		// if a torrent should be included in the returned set or not. Returning true means
 		// it should be included and false means excluded. The ``flags`` argument is the same
@@ -218,15 +218,15 @@ namespace libtorrent
 		// every torrent, it may be used to count the number of torrents of different categories
 		// as well.
 		// 
-		// ``refresh_torrent_status`` takes a vector of ``torrent_status`` structs (for instance
+		// ``refresh_torrent_status`` takes a vector of torrent_status structs (for instance
-		// the same vector that was returned by ``get_torrent_status()``) and refreshes the
+		// the same vector that was returned by get_torrent_status() ) and refreshes the
 		// status based on the ``handle`` member. It is possible to use this function by
 		// first setting up a vector of default constructed ``torrent_status`` objects, only
 		// initializing the ``handle`` member, in order to request the torrent status for
 		// multiple torrents in a single call. This can save a significant amount of time
 		// if you have a lot of torrents.
 		// 
-		// Any ``torrent_status`` object whose ``handle`` member is not referring to a
+		// Any torrent_status object whose ``handle`` member is not referring to a
 		// valid torrent are ignored.
 		void get_torrent_status(std::vector<torrent_status>* ret
 			, boost::function<bool(torrent_status const&)> const& pred
@@ -234,7 +234,7 @@ namespace libtorrent
 		void refresh_torrent_status(std::vector<torrent_status>* ret
 			, boost::uint32_t flags = 0) const;
 
-		// This functions instructs the session to post the state_update_alert_, containing
+		// This functions instructs the session to post the state_update_alert, containing
 		// the status of all torrents whose state changed since the last time this function
 		// was called.
 		// 
@@ -255,23 +255,23 @@ namespace libtorrent
 		torrent_handle find_torrent(sha1_hash const& info_hash) const;
 		std::vector<torrent_handle> get_torrents() const;
 
-		// You add torrents through the ``add_torrent()`` function where you give an
+		// You add torrents through the add_torrent() function where you give an
-		// object with all the parameters. The ``add_torrent()`` overloads will block
+		// object with all the parameters. The add_torrent() overloads will block
 		// until the torrent has been added (or failed to be added) and returns an
-		// error code and a ``torrent_handle``. In order to add torrents more efficiently,
+		// error code and a torrent_handle. In order to add torrents more efficiently,
-		// consider using ``async_add_torrent()`` which returns immediately, without
+		// consider using async_add_torrent() which returns immediately, without
 		// waiting for the torrent to add. Notification of the torrent being added is sent
-		// as add_torrent_alert_.
+		// as add_torrent_alert.
 		// 
-		// The overload that does not take an ``error_code`` throws an exception on
+		// The overload that does not take an error_code throws an exception on
 		// error and is not available when building without exception support.
-		// The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information
+		// The torrent_handle returned by add_torrent() can be used to retrieve information
 		// about the torrent's progress, its peers etc. It is also used to abort a torrent.
 		// 
 		// If the torrent you are trying to add already exists in the session (is either queued
 		// for checking, being checked or downloading) ``add_torrent()`` will throw
-		// libtorrent_exception_ which derives from ``std::exception`` unless ``duplicate_is_error``
+		// libtorrent_exception which derives from ``std::exception`` unless duplicate_is_error
-		// is set to false. In that case, ``add_torrent`` will return the handle to the existing
+		// is set to false. In that case, add_torrent() will return the handle to the existing
 		// torrent.
 		//
 		// all torrent_handles must be destructed before the session is destructed!
@@ -365,10 +365,10 @@ namespace libtorrent
 		//
 		// Before adding the feed, you must set the ``url`` field to the
 		// feed's url. It may point to an RSS or an atom feed.
-		// The returned feed_handle_ is a handle which is used to interact
+		// The returned feed_handle is a handle which is used to interact
 		// with the feed, things like forcing a refresh or querying for
 		// information about the items in the feed. For more information,
-		// see feed_handle_.
+		// see feed_handle.
 		feed_handle add_feed(feed_settings const& feed);
 
 		// Removes a feed from being watched by the session. When this
@@ -411,7 +411,7 @@ namespace libtorrent
 		// client has its own source of bootstrapping nodes.
 		// 
 		// ``set_dht_settings`` sets some parameters availavle to the dht node. See
-		// dht_settings_ for more information.
+		// dht_settings for more information.
 		//
 		// ``is_dht_running()`` returns true if the DHT support has been started and false
 		// otherwise.
@@ -531,11 +531,11 @@ namespace libtorrent
 		// Sets a filter that will be used to reject and accept incoming as well as outgoing
 		// connections based on their originating ip address. The default filter will allow
 		// connections to any ip address. To build a set of rules for which addresses are
-		// accepted and not, see ip_filter_.
+		// accepted and not, see ip_filter.
 		// 
-		// Each time a peer is blocked because of the IP filter, a peer_blocked_alert_ is
+		// Each time a peer is blocked because of the IP filter, a peer_blocked_alert is
 		// generated.
-		// ``get_ip_filter()`` Returns the ip_filter currently in the session. See ip_filter_.
+		// ``get_ip_filter()`` Returns the ip_filter currently in the session. See ip_filter.
 		void set_ip_filter(ip_filter const& f);
 		ip_filter get_ip_filter() const;
 		
@@ -562,11 +562,11 @@ namespace libtorrent
 		// of the interface you want the listener socket bound to. ``listen_on()`` returns the
 		// error code of the operation in ``ec``. If this indicates success, the session is
 		// listening on a port within the specified range. If it fails, it will also
-		// generate an appropriate alert (listen_failed_alert_).
+		// generate an appropriate alert (listen_failed_alert).
 		// 
 		// If all ports in the specified range fails to be opened for listening, libtorrent will
 		// try to use port 0 (which tells the operating system to pick a port that's free). If
-		// that still fails you may see a listen_failed_alert_ with port 0 even if you didn't
+		// that still fails you may see a listen_failed_alert with port 0 even if you didn't
 		// ask to listen on it.
 		// 
 		// It is possible to prevent libtorrent from binding to port 0 by passing in the flag
@@ -575,7 +575,7 @@ namespace libtorrent
 		// The interface parameter can also be a hostname that will resolve to the device you
 		// want to listen on. If you don't specify an interface, libtorrent may attempt to
 		// listen on multiple interfaces (typically 0.0.0.0 and ::). This means that if your
-		// IPv6 interface doesn't work, you may still see a listen_failed_alert_, even though
+		// IPv6 interface doesn't work, you may still see a listen_failed_alert, even though
 		// the IPv4 port succeeded.
 		// 
 		// The ``flags`` parameter can either be 0 or ``session::listen_reuse_address``, which
@@ -656,12 +656,12 @@ namespace libtorrent
 		// `options`` can be used to delete all the files downloaded by this torrent. To do this, pass
 		// in the value ``session::delete_files``. The removal of the torrent is asyncronous, there is
 		// no guarantee that adding the same torrent immediately after it was removed will not throw
-		// a libtorrent_exception_ exception. Once the torrent is deleted, a torrent_deleted_alert_
+		// a libtorrent_exception exception. Once the torrent is deleted, a torrent_deleted_alert
 		// is posted.
 		void remove_torrent(const torrent_handle& h, int options = none);
 
 		// Sets the session settings and the packet encryption settings respectively.
-		// See session_settings_ and pe_settings_ for more information on available
+		// See session_settings and pe_settings for more information on available
 		// options.
 		void set_settings(session_settings const& s);
 		session_settings settings() const;
@@ -760,7 +760,7 @@ namespace libtorrent
 #endif
 
 		// ``pop_alert()`` is used to ask the session if any errors or events has occurred. With
-		// `set_alert_mask()`_ you can filter which alerts to receive through ``pop_alert()``.
+		// set_alert_mask() you can filter which alerts to receive through ``pop_alert()``.
 		// For information about the alert categories, see alerts_.
 		// 
 		// ``pop_alerts()`` pops all pending alerts in a single call. In high performance environments
@@ -793,7 +793,7 @@ namespace libtorrent
 		// To control the max number of alerts that's queued by the session, see
 		// ``session_settings::alert_queue_size``.
 		// 
-		// ``save_resume_data_alert`` and ``save_resume_data_failed_alert`` are always posted, regardelss
+		// save_resume_data_alert and save_resume_data_failed_alert are always posted, regardelss
 		// of the alert mask.
 		std::auto_ptr<alert> pop_alert();
 		void pop_alerts(std::deque<alert*>* alerts);
@@ -837,7 +837,7 @@ namespace libtorrent
 		// 
 		// The upnp object returned by ``start_upnp()`` can be used to add and remove
 		// arbitrary port mappings. Mapping status is returned through the
-		// portmap_alert_ and the portmap_error_alert_. The object will be valid until
+		// portmap_alert and the portmap_error_alert. The object will be valid until
 		// ``stop_upnp()`` is called. See `UPnP and NAT-PMP`_.
 		// 
 		// It is off by default.
@@ -849,7 +849,7 @@ namespace libtorrent
 		// 
 		// The natpmp object returned by ``start_natpmp()`` can be used to add and remove
 		// arbitrary port mappings. Mapping status is returned through the
-		// portmap_alert_ and the portmap_error_alert_. The object will be valid until
+		// portmap_alert and the portmap_error_alert. The object will be valid until
 		// ``stop_natpmp()`` is called. See `UPnP and NAT-PMP`_.
 		// 
 		// It is off by default.

include/libtorrent/torrent_info.hpp

@@ -294,7 +294,7 @@ namespace libtorrent
 		// 
 		// The overloads that takes an ``error_code const&`` never throws if an error occur, they
 		// will simply set the error code to describe what went wrong and not fully initialize the
-		// torrent_info object. The overloads that do not take the extra error_code_ parameter will
+		// torrent_info object. The overloads that do not take the extra error_code parameter will
 		// always throw if an error occurs. These overloads are not available when building without
 		// exception support.
 		// 
@@ -330,17 +330,17 @@ namespace libtorrent
 
 		~torrent_info();
 
-		// The ``file_storage`` object contains the information on how to map the pieces to
+		// The file_storage object contains the information on how to map the pieces to
-		// files. It is separated from the ``torrent_info`` object because when creating torrents
+		// files. It is separated from the torrent_info object because when creating torrents
 		// a storage object needs to be created without having a torrent file. When renaming files
-		// in a storage, the storage needs to make its own copy of the ``file_storage`` in order
+		// in a storage, the storage needs to make its own copy of the file_storage in order
 		// to make its mapping differ from the one in the torrent file.
 		// 
 		// ``orig_files()`` returns the original (unmodified) file storage for this torrent. This
 		// is used by the web server connection, which needs to request files with the original
 		// names. Filename may be chaged using ``torrent_info::rename_file()``.
 		// 
-		// For more information on the ``file_storage`` object, see the separate document on how
+		// For more information on the file_storage object, see the separate document on how
 		// to create torrents.
 		file_storage const& files() const { return m_files; }
 		file_storage const& orig_files() const { return m_orig_files ? *m_orig_files : m_files; }
@@ -466,13 +466,13 @@ namespace libtorrent
 
 		// This function will map a piece index, a byte offset within that piece and
 		// a size (in bytes) into the corresponding files with offsets where that data
-		// for that piece is supposed to be stored. See file_slice_.
+		// for that piece is supposed to be stored. See file_slice.
 		std::vector<file_slice> map_block(int piece, size_type offset, int size) const
 		{ return m_files.map_block(piece, offset, size); }
 
 		// This function will map a range in a specific file into a range in the torrent.
 		// The ``file_offset`` parameter is the offset in the file, given in bytes, where
-		// 0 is the start of the file. See peer_request_.
+		// 0 is the start of the file. See peer_request.
 		// 
 		// The input range is assumed to be valid within the torrent. ``file_offset``
 		// + ``size`` is not allowed to be greater than the file size. ``file_index``