@@ -75,50 +75,89 @@ following associated functions and methods:
7575### Associated Functions
7676
7777* ` fn new() -> Self ` : Creates a new instance of ` Foo ` .
78- * ` fn parse(data: &[u8]) -> Result<Self, protobuf::ParseError> ` : Parses ` data `
79- and returns an instance of ` Foo ` if ` data ` holds a valid wire format
80- representation of ` Foo ` . Otherwise, the function returns an error.
81-
82- ### Methods
8378
79+ ### Traits
80+
81+ For a number of reasons, including gencode size, name collision problems, and
82+ gencode stability, most common functionality on messages is implemented on
83+ traits instead of as inherent implementations.
84+
85+ Most users should import our prelude, which only includes traits and our
86+ ` proto! ` macro and no other types (` use protobuf::prelude::* ` ). If you would
87+ rather avoid preludes, you can always import the specific traits as needed (see
88+ the
89+ <!-- TODO: replace `4.32.0-prerelease` with `latest` once we do a stable release -->
90+ [ documentation here] ( https://docs.rs/protobuf/4.32.0-release/protobuf/trait.Message.html )
91+ for the names and definitions of the traits if you want to import them
92+ directly).
93+
94+ * ` fn parse(data: &[u8]) -> Result<Self, ParseError> ` : Parses a new instance
95+ of a message.
96+ * ` fn parse_dont_enforce_required(data: &[u8]) -> Result<Self, ParseError> ` :
97+ Same as ` parse ` but does not fail on missing proto2 ` required ` fields.
98+ * ` fn clear(&mut self) ` : Clears message.
8499* ` fn clear_and_parse(&mut self, data: &[u8]) -> Result<(), ParseError> ` :
85- Clearing and parsing into existing instance (` protobuf::ClearAndParse `
86- trait).
100+ Clearing and parsing into an existing instance.
101+ * `fn clear_and_parse_dont_enforce_required(&mut self, data: &[ u8] ) ->
102+ Result<(), ParseError>` : Same as ` parse` but does not fail on missing proto2
103+ ` required ` fields.
87104* ` fn serialize(&self) -> Result<Vec<u8>, SerializeError> ` : Serializes the
88105 message to Protobuf wire format. Serialization can fail but rarely will.
89- Failure reasons include exceeding the maximum message size, insufficient
90- memory, and required fields (proto2) that are unset (` protobuf::Serialize `
91- trait).
92- * ` fn clear(&mut self) ` : Clears message (` protobuf::Clear ` trait).
93- * ` fn merge_from(&mut self, other) ` : Merges ` self ` with ` other `
94- (` protobuf::MergeFrom ` trait).
106+ Failure reasons include if the representation exceeds the maximum encoded
107+ message size (must be less than 2 GiB), and ` required ` fields (proto2) that
108+ are unset.
109+ * ` fn take_from(&mut self, other) ` : Moves ` other ` into ` self ` , discarding any
110+ previous state that ` self ` contained.
111+ * ` fn copy_from(&mut self, other) ` : Copies ` other ` into ` self ` , discarding any
112+ previous state that ` self ` contained. ` other ` is unmodified.
113+ * ` fn merge_from(&mut self, other) ` : Merges ` other ` into ` self ` .
95114* ` fn as_view(&self) -> FooView<'_> ` : Returns an immutable handle (view) to
96115 ` Foo ` . This is further covered in the section on proxy types.
97116* ` fn as_mut(&mut self) -> FooMut<'_> ` : Returns a mutable handle (mut) to
98117 ` Foo ` . This is further covered in the section on proxy types.
99118
100- ` Foo ` implements the following traits:
119+ ` Foo ` additionally implements the following std traits:
101120
102- * ` protobuf::ClearAndParse `
103- * ` protobuf::Clear `
104- * ` protobuf::CopyFrom `
105- * ` protobuf::MergeFrom `
106- * ` protobuf::Parse `
107- * ` protobuf::Serialize `
108- * ` protobuf::TakeFrom `
109121* ` std::fmt::Debug `
110122* ` std::default::Default `
111123* ` std::clone::Clone `
112- * ` std::ops::Drop `
113124* ` std::marker::Send `
114125* ` std::marker::Sync `
115126
116- #### Message Proxy Types {#message-proxy-types}
127+ ### Fluently Create New Instances {#proto-macro}
128+
129+ The API design of setters follows our established Protobuf idioms, but the
130+ verbosity when constructing new instances is a mild pain point in certain other
131+ languages. To mitigate this, we offer a ` proto! ` macro, which can be used to
132+ more-succinctly/fluently create new instances.
117133
118- As a consequence of the requirement to support multiple kernels with a single
119- Rust API, we cannot in some situations use native Rust references (` &T ` and
120- ` &mut T ` ), but instead, we need to express these concepts using types - ` View ` s
121- and ` Mut ` s. These situations are shared and mutable references to:
134+ For example, instead of writing this:
135+
136+ ```
137+ let mut msg = SomeMsg::new();
138+ msg.set_x(1);
139+ msg.set_y("hello");
140+ msg.some_submessage_mut().set_z(42);
141+ ```
142+
143+ This macro can be used to write it as follows:
144+
145+ ```
146+ let msg = proto!(SomeMsg {
147+ x: 1,
148+ y: "hello",
149+ some_submsg: SomeSubmsg {
150+ z: 42
151+ }
152+ });
153+ ```
154+
155+ ### Message Proxy Types {#message-proxy-types}
156+
157+ For a number of technical reasons, we have chosen to avoid using native Rust
158+ references (` &T ` and ` &mut T ` ) in certain cases. Instead, we need to express
159+ these concepts using types - ` View ` s and ` Mut ` s. These situations are shared and
160+ mutable references to:
122161
123162* Messages
124163* Repeated fields
@@ -140,6 +179,10 @@ functions with either `&self` or `&mut self` will also be included on the
140179To create an owned message type from a View / Mut type call ` to_owned() ` , which
141180creates a deep copy.
142181
182+ See the corresponding section in our
183+ [ design decisions] ( /reference/rust/rust-design-decisions#view-mut-proxy-types )
184+ documentation for more discussion about why this choice was made.
185+
143186## Nested Types {#nested-types}
144187
145188Given the message declaration:
0 commit comments