[Boost-commit] svn:boost r60788 - trunk/libs/proto/doc

Subject: [Boost-commit] svn:boost r60788 - trunk/libs/proto/doc
From: eric_at_[hidden]
Date: 2010-03-23 01:07:40

Author: eric_niebler
Date: 2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
New Revision: 60788
URL: http://svn.boost.org/trac/boost/changeset/60788

Log:
add an appendix for release notes
Added:
   trunk/libs/proto/doc/release_notes.qbk   (contents, props changed)
Text files modified: 
   trunk/libs/proto/doc/acknowledgements.qbk |     2 +-                                      
   trunk/libs/proto/doc/history.qbk          |     2 +-                                      
   trunk/libs/proto/doc/implementation.qbk   |     2 +-                                      
   trunk/libs/proto/doc/proto.qbk            |     2 ++                                      
   trunk/libs/proto/doc/rationale.qbk        |     2 +-                                      
   5 files changed, 6 insertions(+), 4 deletions(-)

Modified: trunk/libs/proto/doc/acknowledgements.qbk
==============================================================================
--- trunk/libs/proto/doc/acknowledgements.qbk	(original)
+++ trunk/libs/proto/doc/acknowledgements.qbk	2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  /]
 
-[section:acknowledgements Appendix D: Acknowledgements]
+[section:acknowledgements Appendix E: Acknowledgements]
 
 I'd like to thank Joel de Guzman and Hartmut Kaiser for being willing to take a
 chance on using Proto for their work on Spirit-2 and Karma when Proto was

Modified: trunk/libs/proto/doc/history.qbk
==============================================================================
--- trunk/libs/proto/doc/history.qbk	(original)
+++ trunk/libs/proto/doc/history.qbk	2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  /]
 
-[section:history Appendix A: History]
+[section:history Appendix B: History]
 
 [variablelist
 [

Modified: trunk/libs/proto/doc/implementation.qbk
==============================================================================
--- trunk/libs/proto/doc/implementation.qbk	(original)
+++ trunk/libs/proto/doc/implementation.qbk	2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  /]
 
-[section:implementation Appendix C: Implementation Notes]
+[section:implementation Appendix D: Implementation Notes]
 
 [section:sfinae Quick-n-Dirty Type Categorization]
 

Modified: trunk/libs/proto/doc/proto.qbk
==============================================================================
--- trunk/libs/proto/doc/proto.qbk	(original)
+++ trunk/libs/proto/doc/proto.qbk	2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -279,6 +279,8 @@
 [section Appendices]
 [/=================]
 
+[include release_notes.qbk]
+
 [include history.qbk]
 
 [include rationale.qbk]

Modified: trunk/libs/proto/doc/rationale.qbk
==============================================================================
--- trunk/libs/proto/doc/rationale.qbk	(original)
+++ trunk/libs/proto/doc/rationale.qbk	2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -5,7 +5,7 @@
  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  /]
 
-[section:rationale Appendix B: Rationale]
+[section:rationale Appendix C: Rationale]
 
 [/==================================================]
 [section:static_initialization Static Initialization]

Added: trunk/libs/proto/doc/release_notes.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/proto/doc/release_notes.qbk	2010-03-23 01:07:39 EDT (Tue, 23 Mar 2010)
@@ -0,0 +1,76 @@
+[/
+ / Copyright (c) 2008 Eric Niebler
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:release_notes Appendix A: Release Notes]
+
+[/=================]
+[heading Boost 1.43]
+[/=================]
+
+In Boost 1.43, the recommended usage of _extends_ changed slightly. The new
+usage looks like this:
+
+  // my_expr is an expression extension of the Expr parameter
+  template<typename Expr>
+  struct my_expr
+    : proto::extends<Expr, my_expr<Expr>, my_domain>
+  {
+      my_expr(Expr const &expr = Expr())
+        : proto::extends<Expr, my_expr, my_domain>(expr)
+      {}
+
+      // NEW: use the following macro to bring
+      // proto::extends::operator= into scope.
+      BOOST_PROTO_EXTENDS_USING_ASSIGN(my_expr)
+  };
+
+The new thing is the use of the [^[macroref BOOST_PROTO_EXTENDS_USING_ASSIGN]()] macro.
+To allow assignment operators to build expression trees, _extends_ overloads the
+assignment operator. However, for the `my_expr` template, the compiler generates
+a default copy assignment operator that hides the ones in _extends_. This is often
+not desired (although it depends on the syntax you want to allow).
+
+Previously, the recommended usage was to do this:
+
+  // my_expr is an expression extension of the Expr parameter
+  template<typename Expr>
+  struct my_expr
+    : proto::extends<Expr, my_expr<Expr>, my_domain>
+  {
+      my_expr(Expr const &expr = Expr())
+        : proto::extends<Expr, my_expr, my_domain>(expr)
+      {}
+
+      // OLD: don't do it like this anymore.
+      using proto::extends<Expr, my_expr, my_domain>::operator=;
+  };
+
+While this works in the majority of cases, it still doesn't suppress the
+implicit generation of the default assignment operator. As a result, expressions
+of the form `a = b` could either build an expression template or do a copy
+assignment depending on whether the types of `a` and `b` happen to be the
+same. That can lead to subtle bugs, so the behavior was changed.
+
+The [^[macroref BOOST_PROTO_EXTENDS_USING_ASSIGN]()] brings into scope the
+assignment operators defined in _extends_ as well as suppresses the generation
+of the copy assignment operator.
+
+Also note that the _literal_ class template, which uses _extends_, has been chaged
+to use [^[macroref BOOST_PROTO_EXTENDS_USING_ASSIGN]()]. The implications are
+highlighted in the sample code below:
+
+  proto::literal<int> a(1), b(2); // two non-const proto literals
+  proto::literal<int> const c(3); // a const proto literal
+
+  a = b; // No-op. Builds an expression tree and discards it.
+         // Same behavior in 1.42 and 1.43.
+  
+  a = c; // CHANGE! In 1.42, this performed copy assignment, causing
+         // a's value to change to 3. In 1.43, the behavior is now
+         // the same as above: build and discard an expression tree.
+
+[endsect]