doc comment tweaks

4 files changed, 22 insertions, 18 deletions

diff --git a/src/google/protobuf/io/zero_copy_stream_impl.h b/src/google/protobuf/io/zero_copy_stream_impl.h
index d7cf73ff..64e96cd4 100644
--- a/src/google/protobuf/io/zero_copy_stream_impl.h
+++ b/src/google/protobuf/io/zero_copy_stream_impl.h
@@ -33,11 +33,9 @@
 //  Sanjay Ghemawat, Jeff Dean, and others.
 //
 // This file contains common implementations of the interfaces defined in
-// zero_copy_stream.h.  These implementations cover I/O on raw arrays,
-// strings, and file descriptors.  Of course, many users will probably
-// want to write their own implementations of these interfaces specific
-// to the particular I/O abstractions they prefer to use, but these
-// should cover the most common cases.
+// zero_copy_stream.h which are only included in the full (non-lite)
+// protobuf library.  These implementations include Unix file descriptors
+// and C++ iostreams.  See also:  zero_copy_stream_impl_lite.h
 
 #ifndef GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_H__
 #define GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_H__
diff --git a/src/google/protobuf/io/zero_copy_stream_impl_lite.h b/src/google/protobuf/io/zero_copy_stream_impl_lite.h
index 59f18258..153f543e 100644
--- a/src/google/protobuf/io/zero_copy_stream_impl_lite.h
+++ b/src/google/protobuf/io/zero_copy_stream_impl_lite.h
@@ -33,11 +33,13 @@
 //  Sanjay Ghemawat, Jeff Dean, and others.
 //
 // This file contains common implementations of the interfaces defined in
-// zero_copy_stream.h.  These implementations cover I/O on raw arrays,
-// strings, and file descriptors.  Of course, many users will probably
-// want to write their own implementations of these interfaces specific
-// to the particular I/O abstractions they prefer to use, but these
-// should cover the most common cases.
+// zero_copy_stream.h which are included in the "lite" protobuf library.
+// These implementations cover I/O on raw arrays and strings, as well as
+// adaptors which make it easy to implement streams based on traditional
+// streams.  Of course, many users will probably want to write their own
+// implementations of these interfaces specific to the particular I/O
+// abstractions they prefer to use, but these should cover the most common
+// cases.
 
 #ifndef GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_LITE_H__
 #define GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_LITE_H__
diff --git a/src/google/protobuf/message.h b/src/google/protobuf/message.h
index eecd91a7..54b596d5 100644
--- a/src/google/protobuf/message.h
+++ b/src/google/protobuf/message.h
@@ -32,9 +32,10 @@
 //  Based on original Protocol Buffers design by
 //  Sanjay Ghemawat, Jeff Dean, and others.
 //
-// This file contains the abstract interface for all protocol messages.
-// Although it's possible to implement this interface manually, most users
-// will use the protocol compiler to generate implementations.
+// Defines Message, the abstract interface implemented by non-lite
+// protocol message objects.  Although it's possible to implement this
+// interface manually, most users will use the protocol compiler to
+// generate implementations.
 //
 // Example usage:
 //
@@ -168,7 +169,8 @@ struct Metadata {
 };
 
 // Returns the EnumDescriptor for enum type E, which must be a
-// proto-declared enum type.
+// proto-declared enum type.  Code generated by the protocol compiler
+// will include specializations of this template for each enum type declared.
 template <typename E>
 const EnumDescriptor* GetEnumDescriptor();
 
diff --git a/src/google/protobuf/message_lite.h b/src/google/protobuf/message_lite.h
index d289d8c7..ebf4ba3c 100644
--- a/src/google/protobuf/message_lite.h
+++ b/src/google/protobuf/message_lite.h
@@ -33,6 +33,8 @@
 //  Based on original Protocol Buffers design by
 //  Sanjay Ghemawat, Jeff Dean, and others.
 //
+// Defines MessageLite, the abstract interface implemented by all (lite
+// and non-lite) protocol message objects.
 
 #ifndef GOOGLE_PROTOBUF_MESSAGE_LITE_H__
 #define GOOGLE_PROTOBUF_MESSAGE_LITE_H__
@@ -45,15 +47,15 @@ namespace protobuf {
 
 // Interface to light weight protocol messages.
 //
-// This interface is implemented by all protocol message objects.  Most
-// users will be more interested in the Message interface, which is a
-// subclass of MessageLite. Use MessageLite instead when you only need
+// This interface is implemented by all protocol message objects.  Non-lite
+// messages additionally implement the Message interface, which is a
+// subclass of MessageLite.  Use MessageLite instead when you only need
 // the subset of features which it supports -- namely, nothing that uses
 // descriptors or reflection.  You can instruct the protocol compiler
 // to generate classes which implement only MessageLite, not the full
 // Message interface, by adding the following line to the .proto file:
 //
-//  option optimize_for = LITE_RUNTIME;
+//   option optimize_for = LITE_RUNTIME;
 //
 // This is particularly useful on resource-constrained systems where
 // the full protocol buffers runtime library is too big.