Mojo C++ bindings: change the first template parameter of StructTraits and UnionTraits.

mojo/public/cpp/bindings/struct_traits.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef MOJO_PUBLIC_CPP_BINDINGS_STRUCT_TRAITS_H_
 #define MOJO_PUBLIC_CPP_BINDINGS_STRUCT_TRAITS_H_
 
 namespace mojo {
 
 // This must be specialized for any type |T| to be serialized/deserialized as
-// a mojom struct of type |MojomType|.
+// a mojom struct. |DataViewType| is the corresponding data view type of the
+// mojom struct. For example, if the mojom struct is example.Foo,
+// |DataViewType| will be example::FooDataView, which can also be referred to by
+// example::Foo::DataView (in chromium) and example::blink::Foo::DataView (in
+// blink).
 //
 // Each specialization needs to implement a few things:
 //   1. Static getters for each field in the Mojom type. These should be
 //      of the form:
 //
 //        static <return type> <field name>(const T& input);
 //
 //      and should return a serializable form of the named field as extracted
 //      from |input|.
 //
 //      Serializable form of a field:
-//        Value or reference of the same type used in |MojomType|, or the
-//        following alternatives:
+//        Value or reference of the same type used in the generated stuct
+//        wrapper type, or the following alternatives:
 //        - string:
 //          Value or reference of any type that has a StringTraits defined.
-//          Supported by default: base::StringPiece, std::string.
+//          Supported by default: base::StringPiece, std::string, mojo::String,
+//          WTF::String (in blink).
 //
 //        - array:
 //          Value or reference of any type that has an ArrayTraits defined.
-//          Supported by default: std::vector, WTF::Vector (in blink), CArray.
+//          Supported by default: std::vector, CArray, mojo::Array, WTF::Vector
+//          (in blink), mojo::WTFArray (in blink).
 //
 //        - map:
 //          Value or reference of any type that has a MapTraits defined.
-//          Supported by default: std::map.
+//          Supported by default: std::map, std::unordered_map, mojo::Map,
+//          WTF::HashMap (in blink), mojo::WTFMap (in blink).
 //
 //        - struct:
 //          Value or reference of any type that has a StructTraits defined.
 //
 //        - enum:
 //          Value of any type that has an EnumTraits defined.
 //
+//      For any nullable string/struct/array/map/union field you could also
+//      return value or reference of base::Optional<T>/WTF::Optional<T>, if T
+//      has the right *Traits defined.
+//
 //      During serialization, getters for string/struct/array/map/union fields
 //      are called twice (one for size calculation and one for actual
 //      serialization). If you want to return a value (as opposed to a
 //      reference) from these getters, you have to be sure that constructing and
 //      copying the returned object is really cheap.
 //
 //      Getters for fields of other types are called once.
 //
 //   2. A static Read() method to set the contents of a |T| instance from a
-//      |MojomType|DataView (e.g., if |MojomType| is test::Example, the data
-//      view will be test::ExampleDataView).
+//      DataViewType.
 //
-//        static bool Read(|MojomType|DataView data, T* output);
+//        static bool Read(DataViewType data, T* output);
 //
-//      The generated |MojomType|DataView type provides a convenient,
-//      inexpensive view of a serialized struct's field data. The caller
-//      guarantees that |!data.is_null()|.
+//      The generated DataViewType provides a convenient, inexpensive view of a
+//      serialized struct's field data. The caller guarantees that
+//      |!data.is_null()|.
 //
 //      Returning false indicates invalid incoming data and causes the message
 //      pipe receiving it to be disconnected. Therefore, you can do custom
 //      validation for |T| in this method.
 //
 //   3. [Optional] A static IsNull() method indicating whether a given |T|
 //      instance is null:
 //
 //        static bool IsNull(const T& input);
 //
@@ skipping 35 matching lines @@
 //      to getters. After serialization is done, it calls TearDownContext() so
 //      that you can do any necessary cleanup.
 //
 // In the description above, methods having an |input| parameter define it as
 // const reference of T. Actually, it can be a non-const reference of T too.
 // E.g., if T contains Mojo handles or interfaces whose ownership needs to be
 // transferred. Correspondingly, it requies you to always give non-const T
 // reference/value to the Mojo bindings for serialization:
 //    - if T is used in the "type_mappings" section of a typemap config file,
 //      you need to declare it as pass-by-value:
-//        type_mappings = [ "MojomType=T(pass_by_value)" ]
-//    - if another type U's StructTraits has a getter for T, it needs to return
-//      non-const reference/value.
+//        type_mappings = [ "MojomType=T(move_only)" ]
+//      or
+//        type_mappings = [ "MojomType=T(copyable_pass_by_value)" ]
+//
+//    - if another type U's StructTraits/UnionTraits has a getter for T, it
+//      needs to return non-const reference/value.
 //
 // EXAMPLE:
 //
 // Mojom definition:
 //   struct Bar {};
 //   struct Foo {
 //     int32 f_integer;
 //     string f_string;
 //     array<string> f_string_array;
 //     Bar f_bar;
 //   };
 //
 // StructTraits for Foo:
 //   template <>
-//   struct StructTraits<Foo, CustomFoo> {
+//   struct StructTraits<FooDataView, CustomFoo> {
 //     // Optional methods dealing with null:
 //     static bool IsNull(const CustomFoo& input);
 //     static void SetToNull(CustomFoo* output);
 //
 //     // Field getters:
 //     static int32_t f_integer(const CustomFoo& input);
 //     static const std::string& f_string(const CustomFoo& input);
 //     static const std::vector<std::string>& f_string_array(
 //         const CustomFoo& input);
 //     // Assuming there is a StructTraits<Bar, CustomBar> defined.
 //     static const CustomBar& f_bar(const CustomFoo& input);
 //
 //     static bool Read(FooDataView data, CustomFoo* output);
 //   };
 //
-template <typename MojomType, typename T>
+template <typename DataViewType, typename T>
 struct StructTraits;
 
 }  // namespace mojo
 
 #endif  // MOJO_PUBLIC_CPP_BINDINGS_STRUCT_TRAITS_H_