[PATCH] Initial user documentation for TR1 to C++11 migration.

[Edwin Vane]

  I'm requesting some big organizational changes to make the document a little clearer. At some point I stopped making grammar fixes once I saw bigger changes were necessary in those sections.

  The over-arching thing to keep in mind is the audience for this document: someone changing their code from TR1 to C++11. This includes people wanting to automate this process in clang-modernize. To that end, make sure the differences are highly visible as this tells the audience what they need to do. Similarities can be left out or put in an appendix if you think it's necessary.


================
Comment at: docs/TR1Porting.rst:23
@@ +22,3 @@
+
+- The C++11 interface is more mature, the interfaces have more functionality or
+  are easier to use.
----------------
replace the , with a ;

================
Comment at: docs/TR1Porting.rst:25
@@ +24,3 @@
+  are easier to use.
+- The C++11 interface takes advantage of the new language features (e.g: move
+  semantics, perfect forwarding).
----------------
`of the new` => `of new`.

I'd remove the parenthetical statement and replace with: `...language features: move semantics, perfect forwarding, etc.`

================
Comment at: docs/TR1Porting.rst:30
@@ +29,3 @@
+- Popular TR1 implementations use different conventions which limits
+  interoperability. Using C++11 will work seamlessly across all C++11 compliant
+  libraries.
----------------
Hyphen between `C++11` and `compliant`

================
Comment at: docs/TR1Porting.rst:43
@@ +42,3 @@
+Multiple TR1 implementations are available. They have their own conventions on
+how to include TR1 components. The following table list the vendors and their
+respective conventions:
----------------
`list` => `lists`.

================
Comment at: docs/TR1Porting.rst:57-58
@@ +56,4 @@
+
+Aside from the different header include style all declarations reside in the
+namespace ``std::tr1``.
+
----------------
> Aside from the differing header include styles, declarations from each vendor reside in the namespace std::tr1

================
Comment at: docs/TR1Porting.rst:79
@@ +78,3 @@
+This section describes changes that aren’t unique to one header but instead are
+spread across severals.
+
----------------
`severals` => `several`.

================
Comment at: docs/TR1Porting.rst:75
@@ +74,3 @@
+
+Sparse changes
+==============
----------------
I think it would be clearer if what you call 'changes' you describe as 'differences'. This document describes how to go from tr1 to C++11 so we want to know how they differ.

================
Comment at: docs/TR1Porting.rst:91
@@ +90,3 @@
+
+Becomes::
+
----------------
lower case 'b'.

================
Comment at: docs/TR1Porting.rst:101
@@ +100,3 @@
+
+- A template specialization for some algorithms (e.g: ``std::swap()``).
+- Overloaded IO operators for stream input/output (e.g: ``operator<<()``).
----------------
I'm seeing this pattern multiple times so this comment is for all later occurrences. Try to avoid parenthetical statements. In this specific case you could say instead: `... algorithms, e.g. std::swap()`.

================
Comment at: docs/TR1Porting.rst:110
@@ +109,3 @@
+and as such no changes is needed with them in general.
+
+
----------------
I'm not sure what the point of this section is. I understand you're saying that TR1 offers some functionality but are you saying this functionality doesn't exist in C++11? Or are you saying C++11 provides them you just need to remove tr1:: if it's used? Since this is a guide for porting TR1->C++11 please be specific as to what a user would have to do to their code.

================
Comment at: docs/TR1Porting.rst:115
@@ +114,3 @@
+
+In TR1 function objects inherit ``std::unary_function/std::binary_function`` to
+provide typedefs for the result type and the argument(s) type(s). This practice
----------------
Comma after TR1.

================
Comment at: docs/TR1Porting.rst:119
@@ +118,3 @@
+more generic ``std::function``. This document assumes that the ported code
+doesn’t rely directly on the inheritance of
+``std::unary_function/std::binary_function`` but instead only to the typedefs
----------------
Remove 'directly'.

================
Comment at: docs/TR1Porting.rst:139-142
@@ +138,6 @@
+
+* | std::tr1::tuple_size (std::array specialization)
+  | std::tr1::tuple_element (std::array specialization)
+
+* std::tr1::get (std::array specialization)
+
----------------
What are the point of these bullets? They have no explanation.

I think this section could be better organized to highlight the differences. From what I'm reading here, tr1::array can be replaced with std::array with the exception of `assign()` -> `fill()`.

Focus on what changes are needed to code and less on differences in template specializations. All we're aiming to do is have code that compiles after tr1->c++11 transform and behaves the same way at runtime. We don't care if the implementation is different. That's a topic for another document.

================
Comment at: docs/TR1Porting.rst:173
@@ +172,3 @@
+
+* assoc_laguerre, assoc_laguerref, assoc_laguerrel, assoc_legendre,
+  assoc_legendref, assoc_legendrel, beta, betaf, betal, comp_ellint_1,
----------------
Why a single bullet? Perhaps a table or something else that's easier to read instead of a massive block of text.

================
Comment at: docs/TR1Porting.rst:196-210
@@ +195,17 @@
+
+* | std::tr1::reference_wrapper
+  | std::tr1::ref
+  | std::tr1::cref
+
+* | std::tr1::result_of
+
+* | std::tr1::mem_fn
+
+* | std::tr1::is_bind_expression
+  | std::tr1::is_placeholder
+  | std::tr1::bind
+  | std::tr1::placeholders
+
+* | std::tr1::bad_function_call
+  | std::tr1::function
+
----------------
Again, I'm not sure it's necessary to list all the types that behave the same way. Focus on the differences. Apply this suggestion in all the sections below.

================
Comment at: docs/TR1Porting.rst:215
@@ +214,3 @@
+
+  * :ref:`ref-hash_string_specialization`
+
----------------
Are these references really necessary. I would just move the content of the reference (minus the header) under this hash item. If you remove the list of types that have no differences like I suggest above that would leave this hash item on it's own. I'd suggest then removing the bullet completely and just describe the difference.

================
Comment at: docs/TR1Porting.rst:253
@@ +252,3 @@
+
+The TR1 additions to this header are *mostly compatible* with C++11 with two
+exceptions described below.
----------------
additions? Do you mean the stuff in TR1 or the stuff in C++11 that's new from TR1?


http://llvm-reviews.chandlerc.com/D1740

BRANCH
  tr1-doc

ARCANIST PROJECT
  clang-tools-extra