[PATCH] Initial user documentation for TR1 to C++11 migration.
Guillaume Papin
guillaume.papin at epitech.eu
Fri Sep 27 07:27:42 PDT 2013
I restructured the document as requested.
I'm not sure if I
> 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.
I'm not sure if the new version really address this. I think once `clang-modernize` can transform some TR1 components we can put a status table (similar to what is done with the C++11 status page for Clang) and link to corresponding section in the document if needed.
================
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.
----------------
Edwin Vane wrote:
> replace the , with a ;
Done.
================
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).
----------------
Edwin Vane wrote:
> `of the new` => `of new`.
>
> I'd remove the parenthetical statement and replace with: `...language features: move semantics, perfect forwarding, etc.`
Done.
================
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.
----------------
Edwin Vane wrote:
> Hyphen between `C++11` and `compliant`
Done.
================
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:
----------------
Edwin Vane wrote:
> `list` => `lists`.
Fixed.
================
Comment at: docs/TR1Porting.rst:57-58
@@ +56,4 @@
+
+Aside from the different header include style all declarations reside in the
+namespace ``std::tr1``.
+
----------------
Edwin Vane wrote:
> > Aside from the differing header include styles, declarations from each vendor reside in the namespace std::tr1
Done.
================
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.
+
----------------
Edwin Vane wrote:
> `severals` => `several`.
Fixed.
================
Comment at: docs/TR1Porting.rst:91
@@ +90,3 @@
+
+Becomes::
+
----------------
Edwin Vane wrote:
> lower case 'b'.
Done.
================
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<<()``).
----------------
Edwin Vane wrote:
> 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()`.
Fixed and will keep this in mind, you already told me that before IIRC.
================
Comment at: docs/TR1Porting.rst:110
@@ +109,3 @@
+and as such no changes is needed with them in general.
+
+
----------------
Edwin Vane wrote:
> 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.
I'm saying your second point "...C++11 provides them you just need to remove tr1:: if it's used".
Following another comment I stopped listing what is straightforward to change. I removed this section since it is straightforward in all headers it applies.
================
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
----------------
Edwin Vane wrote:
> Comma after TR1.
Fixed.
================
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
----------------
Edwin Vane wrote:
> Remove 'directly'.
Done.
================
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,
----------------
Edwin Vane wrote:
> Why a single bullet? Perhaps a table or something else that's easier to read instead of a massive block of text.
Replaced with a table as suggested.
I didn't want to use a list because it felt quite long for nothing. I just wanted the people to be able to grep the function name in the page and find out there is no equivalent.
This is the only "blocking" change to port from TR1 to C++11. Should I put a note to say that it can be replaced by a boost library? http://www.boost.org/doc/libs/1_54_0/libs/math/doc/html/math_toolkit/main_intro.html / http://www.boost.org/doc/libs/1_54_0/libs/math/doc/html/special.html
================
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
+
----------------
Edwin Vane wrote:
> 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.
Okay done. I guess this listing is only useful to the migrator when writing the transforms.
================
Comment at: docs/TR1Porting.rst:215
@@ +214,3 @@
+
+ * :ref:`ref-hash_string_specialization`
+
----------------
Edwin Vane wrote:
> 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.
I'm not sure if I followed your advice exactly. I left out the sub-section for the difference so it shows up in the TOC of the page.
I used the same way of describing the differences as in ``<array>``.
================
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.
----------------
Edwin Vane wrote:
> additions? Do you mean the stuff in TR1 or the stuff in C++11 that's new from TR1?
I reworded this to use the same sentence as used in the ``<array>`` description.
================
Comment at: docs/TR1Porting.rst:75
@@ +74,3 @@
+
+Sparse changes
+==============
----------------
Edwin Vane wrote:
> 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.
I removed this section, the sub-section have been "flattened" instead.
I'm not sure if I followed this advice entirely. Let me know if it's still not correct.
================
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)
+
----------------
Edwin Vane wrote:
> 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.
I used the bullets in case the readers wanted to search in the webpage the class he wants to change. I removed these listings now. Now the header descriptions contains only the differences or a note saying that there is no difference.
http://llvm-reviews.chandlerc.com/D1740
BRANCH
tr1-doc
ARCANIST PROJECT
clang-tools-extra
More information about the cfe-commits
mailing list