start a document of changes from 1.1 to 1.2

docs/index.rst

@@ -11,6 +11,7 @@
 * examples_
 * overview_
 * documentation_
+* `libtorrent 1.2`_
 * contributing_
 * building_
 * troubleshooting_
@@ -67,6 +68,7 @@ libtorrent
 .. _examples: examples.html
 .. _overview: manual-ref.html
 .. _documentation: reference.html
+.. _`libtorrent 1.2`: upgrade_to_1.2.html
 .. _troubleshooting: troubleshooting.html
 .. _`tuning`: tuning.html
 .. _screenshot: client_test.png

docs/makefile

@@ -50,6 +50,7 @@ TARGETS = index \
 	hacking \
 	streaming \
 	tutorial \
+	upgrade_to_1.2 \
 	single-page-ref \
 	$(REFERENCE_TARGETS)
 

docs/upgrade_to_1.2.rst

@@ -0,0 +1,90 @@
+===========================
+Upgrading to libtorrent 1.2
+===========================
+
+:Author: Arvid Norberg, arvid@libtorrent.org
+:Version: 1.2.0
+
+libtorrent version 1.2 comes with some significant updates in the API.
+This document summarizes the changes affecting library users.
+
+C++98 no longer supported
+-------------------------
+
+With libtorrent 1.2, C++98 is no longer supported, you need a compiler capable
+of at least C++11 to build libtorrent.
+
+This also means libtorrent types now support move.
+
+forward declaring libtorrent types deprecated
+---------------------------------------------
+
+Clients are discouraged from forward declaring types from libtorrent.
+Instead, include the <libtorrent/fwd.hpp> header.
+
+A future release will intrduce ABI versioning using an inline namespace, which will break any forward declarations by clients.
+
+There is a new namespace alias, ``lt`` which is shorthand for ``libtorrent``.
+In the future, ``libtorrent`` will be the alias and ``lt`` the namespace name.
+With no forward declarations inside libtorrent's namespace though, there should not be any reason for clients to re-open the namespace.
+
+announce entry multi-home support
+---------------------------------
+
+The ``announce_entry`` type now captures status on individual endpoints, as opposed to treating every tracker behind the same name as a single tracker.
+This means some properties has moved into the ``announce_endpoint`` structure, and an announce entry has 0 or more endpoints.
+
+alerts no longer cloneable
+--------------------------
+
+As part of the transition to a more efficient handling of alerts, 1.1 allocated them in a contiguous, heterogeneous, vector.
+This means they are no longer heap allocated nor held by a smart pointer.
+The ``clone()`` member on alerts was deprecated in 1.1 and removed in 1.2.
+To pass alerts across threads, instead pull out the relevant information from the alerts and pass that across.
+
+boost replaced by std
+---------------------
+
+``boost::shared_ptr`` has been replaced by ``std::shared_ptr`` in the libtorrent API.
+The same goes for ``<cstdint>`` types, instead of ``boost::int64_t``, libtorrent now uses ``std::int64_t``.
+Instead of ``boost::array``, ``std::array`` is used, and ``boost::function`` has been replaced by ``std::fuction``.
+
+strong typedefs
+---------------
+
+In order to strengthen type-safety, libtorrent now uses special types to represent certain indexes and ID types.
+Any integer referring to a piece index, now has the type ``piece_index_t``, and indices to files in a torrent, use ``file_index_t``.
+Similarly, time points and duration now use ``time_point`` and ``duration`` from the ``<chrono>`` standard library.
+
+The specific types have typedefs at ``lt::time_point`` and ``lt::duration``, and the clock used by libtorrent is ``lt::clock_type``.`
+
+span<> and string_view
+----------------------
+
+The interface has adopted ``string_view`` (from boost for now) and ``span<>`` (custom implementation for now).
+This means some function calls that previously took ``char const*`` or ``std::string`` may now take an ``lt::string_view``.
+Similarly, functions that previously would take a pointer and length pair will now take a ``span<>``.
+
+periphery utility functions no longer exported
+----------------------------------------------
+
+Historically, libtorrent has exported functions not essential to its core bittorrent functionality.
+Such as filesystem functions like ``directory``, ``file`` classes and ``remove``, ``create_directory`` functions.
+Path manipulation functions like ``combine_path``, ``extension``, ``split_path`` etc.
+String manipulation functions like ``from_hex`` and ``to_hex``.
+Time functions like ``time_now``. These functions are no longer available to clients, and some have been removed from the library.
+Instead, it is recommended to use boost.filesystem or the experimental filesystem TS.
+
+plugins
+-------
+
+libtorrent session plugins no longer have all callbacks called unconditionally.
+The callback has to register which callbacks it's interested in receiving by returning a bitmask from ``std::uint32_t implemented_features()``.
+The return value is documented in the plugin class.
+
+RSS functions removed
+---------------------
+
+The deprecated RSS functions have been removed from the library interface.
+
+

include/libtorrent/kademlia/dht_state.hpp

@@ -53,9 +53,9 @@ namespace libtorrent { namespace dht {
 	// This structure helps to store and load the state
 	// of the ``dht_tracker``.
 	// At this moment the library is only a dual stack
-	// implementation of the DHT. See BEP38_
+	// implementation of the DHT. See `BEP 32`_
 	//
-	// .. _BEP32: http://bittorrent.org/beps/bep_0032.html
+	// .. _`BEP 32`: http://bittorrent.org/beps/bep_0032.html
 	struct TORRENT_EXPORT dht_state
 	{
 		node_ids_t nids;