Snap for 8270536 from 0af506eab5a6d52635e775e0ad9b6439da826a3a to tm-releaseandroid-vts-13.0_r8android-vts-13.0_r7android-vts-13.0_r6android-vts-13.0_r5android-vts-13.0_r4android-vts-13.0_r3android-vts-13.0_r2android-vts-13.0_r1android-security-13.0.0_r9android-security-13.0.0_r8android-security-13.0.0_r7android-security-13.0.0_r6android-security-13.0.0_r5android-security-13.0.0_r4android-security-13.0.0_r3android-security-13.0.0_r2android-security-13.0.0_r19android-security-13.0.0_r18android-security-13.0.0_r17android-security-13.0.0_r16android-security-13.0.0_r15android-security-13.0.0_r14android-security-13.0.0_r13android-security-13.0.0_r12android-security-13.0.0_r11android-security-13.0.0_r10android-security-13.0.0_r1android-platform-13.0.0_r9android-platform-13.0.0_r8android-platform-13.0.0_r7android-platform-13.0.0_r6android-platform-13.0.0_r5android-platform-13.0.0_r4android-platform-13.0.0_r3android-platform-13.0.0_r21android-platform-13.0.0_r20android-platform-13.0.0_r2android-platform-13.0.0_r19android-platform-13.0.0_r18android-platform-13.0.0_r17android-platform-13.0.0_r16android-platform-13.0.0_r15android-platform-13.0.0_r14android-platform-13.0.0_r13android-platform-13.0.0_r12android-platform-13.0.0_r11android-platform-13.0.0_r10android-platform-13.0.0_r1android-cts-13.0_r8android-cts-13.0_r7android-cts-13.0_r6android-cts-13.0_r5android-cts-13.0_r4android-cts-13.0_r3android-cts-13.0_r2android-cts-13.0_r1android-13.0.0_r8android-13.0.0_r7android-13.0.0_r6android-13.0.0_r5android-13.0.0_r4android-13.0.0_r31android-13.0.0_r3android-13.0.0_r2android-13.0.0_r12android-13.0.0_r1android13-tests-releaseandroid13-security-releaseandroid13-s3-releaseandroid13-s2-releaseandroid13-s1-releaseandroid13-releaseandroid13-platform-releaseandroid13-gsi

Change-Id: I1afc3e5e65c4576b5c9584ef20cb5bdbf6211d5a

1 files changed, 93 insertions, 2 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 8eee9d3..d88e029 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,97 @@
-//! Library to read and write protocol buffers data.
+//! # Library to read and write protocol buffers data
+//!
+//! # Version 2 is stable
+//!
+//! Currently developed branch of rust-protobuf [is 3](https://docs.rs/protobuf/%3E=3.0.0-alpha).
+//! It has the same spirit as version 2, but contains numerous improvements like:
+//! * runtime reflection for mutability, not just for access
+//! * protobuf text format and JSON parsing (which rely on reflection)
+//! * dynamic message support: work with protobuf data without generating code from schema
+//!
+//! Stable version of rust-protobuf will be supported until version 3 released.
+//!
+//! [Tracking issue for version 3](https://github.com/stepancheg/rust-protobuf/issues/518).
+//!
+//! # How to generate rust code
+//!
+//! There are several ways to generate rust code from `.proto` files
+//!
+//! ## Invoke `protoc` programmatically with protoc-rust crate (recommended)
+//!
+//! Have a look at readme in [protoc-rust crate](https://docs.rs/protoc-rust/=2).
+//!
+//! ## Use pure rust protobuf parser and code generator
+//!
+//! Readme should be in
+//! [protobuf-codegen-pure crate](https://docs.rs/protobuf-codegen-pure/=2).
+//!
+//! ## Use protoc-gen-rust plugin
+//!
+//! Readme is [here](https://docs.rs/protobuf-codegen/=2).
+//!
+//! ## Generated code
+//!
+//! Have a look at generated files (for current development version),
+//! used internally in rust-protobuf:
+//!
+//! * [descriptor.rs](https://github.com/stepancheg/rust-protobuf/blob/master/protobuf/src/descriptor.rs)
+//!   for [descriptor.proto](https://github.com/stepancheg/rust-protobuf/blob/master/protoc-bin-vendored/include/google/protobuf/descriptor.proto)
+//!   (that is part of Google protobuf)
+//!
+//! # Copy on write
+//!
+//! Rust-protobuf can be used with [bytes crate](https://github.com/tokio-rs/bytes).
+//!
+//! To enable `Bytes` you need to:
+//!
+//! 1. Enable `with-bytes` feature in rust-protobuf:
+//!
+//! ```
+//! [dependencies]
+//! protobuf = { version = "~2.0", features = ["with-bytes"] }
+//! ```
+//!
+//! 2. Enable bytes option
+//!
+//! with `Customize` when codegen is invoked programmatically:
+//!
+//! ```ignore
+//! protoc_rust::run(protoc_rust::Args {
+//!     ...
+//!     customize: Customize {
+//!         carllerche_bytes_for_bytes: Some(true),
+//!         carllerche_bytes_for_string: Some(true),
+//!         ..Default::default()
+//!     },
+//! });
+//! ```
+//!
+//! or in `.proto` file:
+//!
+//! ```ignore
+//! import "rustproto.proto";
+//!
+//! option (rustproto.carllerche_bytes_for_bytes_all) = true;
+//! option (rustproto.carllerche_bytes_for_string_all) = true;
+//! ```
+//!
+//! With these options enabled, fields of type `bytes` or `string` are
+//! generated as `Bytes` or `Chars` respectively. When `CodedInputStream` is constructed
+//! from `Bytes` object, fields of these types get subslices of original `Bytes` object,
+//! instead of being allocated on heap.
+//!
+//! # Accompanying crates
+//!
+//! * [`protoc-rust`](https://docs.rs/protoc-rust/=2)
+//!   and [`protobuf-codegen-pure`](https://docs.rs/protobuf-codegen-pure/=2)
+//!   can be used to rust code from `.proto` crates.
+//! * [`protobuf-codegen`](https://docs.rs/protobuf-codegen/=2) for `protoc-gen-rust` protoc plugin.
+//! * [`protoc`](https://docs.rs/protoc/=2) crate can be used to invoke `protoc` programmatically.
+//! * [`protoc-bin-vendored`](https://docs.rs/protoc-bin-vendored/=2) contains `protoc` command
+//!   packed into the crate.
 
 #![deny(missing_docs)]
-#![deny(broken_intra_doc_links)]
+#![deny(rustdoc::broken_intra_doc_links)]
 
 #[cfg(feature = "bytes")]
 extern crate bytes;
@@ -90,6 +180,7 @@ mod zigzag;
 mod misc;
 
 mod buf_read_iter;
+mod buf_read_or_reader;
 
 /// This symbol is in generated `version.rs`, include here for IDE
 #[cfg(never)]