Merge pull request #845 from jskeet/xmldocs

Extract XML documentation in a primitive but reasonably-effective way

cmake/libprotoc.cmake

@@ -14,6 +14,7 @@ set(libprotoc_files
   ${protobuf_source_dir}/src/google/protobuf/compiler/cpp/cpp_primitive_field.cc
   ${protobuf_source_dir}/src/google/protobuf/compiler/cpp/cpp_service.cc
   ${protobuf_source_dir}/src/google/protobuf/compiler/cpp/cpp_string_field.cc
+  ${protobuf_source_dir}/src/google/protobuf/compiler/csharp/csharp_doc_comment.cc
   ${protobuf_source_dir}/src/google/protobuf/compiler/csharp/csharp_enum.cc
   ${protobuf_source_dir}/src/google/protobuf/compiler/csharp/csharp_enum_field.cc
   ${protobuf_source_dir}/src/google/protobuf/compiler/csharp/csharp_field_base.cc

csharp/src/AddressBook/Addressbook.cs

@@ -73,6 +73,7 @@ namespace Google.Protobuf.Examples.AddressBook {
       return new Person(this);
     }
 
+    /// <summary>Field number for the "name" field.</summary>
     public const int NameFieldNumber = 1;
     private string name_ = "";
     public string Name {
@@ -82,8 +83,12 @@ namespace Google.Protobuf.Examples.AddressBook {
       }
     }
 
+    /// <summary>Field number for the "id" field.</summary>
     public const int IdFieldNumber = 2;
     private int id_;
+    /// <summary>
+    ///  Unique ID number for this person.
+    /// </summary>
     public int Id {
       get { return id_; }
       set {
@@ -91,6 +96,7 @@ namespace Google.Protobuf.Examples.AddressBook {
       }
     }
 
+    /// <summary>Field number for the "email" field.</summary>
     public const int EmailFieldNumber = 3;
     private string email_ = "";
     public string Email {
@@ -100,6 +106,7 @@ namespace Google.Protobuf.Examples.AddressBook {
       }
     }
 
+    /// <summary>Field number for the "phones" field.</summary>
     public const int PhonesFieldNumber = 4;
     private static readonly pb::FieldCodec<global::Google.Protobuf.Examples.AddressBook.Person.Types.PhoneNumber> _repeated_phones_codec
         = pb::FieldCodec.ForMessage(34, global::Google.Protobuf.Examples.AddressBook.Person.Types.PhoneNumber.Parser);
@@ -251,6 +258,7 @@ namespace Google.Protobuf.Examples.AddressBook {
           return new PhoneNumber(this);
         }
 
+        /// <summary>Field number for the "number" field.</summary>
         public const int NumberFieldNumber = 1;
         private string number_ = "";
         public string Number {
@@ -260,6 +268,7 @@ namespace Google.Protobuf.Examples.AddressBook {
           }
         }
 
+        /// <summary>Field number for the "type" field.</summary>
         public const int TypeFieldNumber = 2;
         private global::Google.Protobuf.Examples.AddressBook.Person.Types.PhoneType type_ = global::Google.Protobuf.Examples.AddressBook.Person.Types.PhoneType.MOBILE;
         public global::Google.Protobuf.Examples.AddressBook.Person.Types.PhoneType Type {
@@ -356,6 +365,9 @@ namespace Google.Protobuf.Examples.AddressBook {
 
   }
 
+  /// <summary>
+  ///  Our address book file is just one of these.
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class AddressBook : pb::IMessage<AddressBook> {
     private static readonly pb::MessageParser<AddressBook> _parser = new pb::MessageParser<AddressBook>(() => new AddressBook());
@@ -383,6 +395,7 @@ namespace Google.Protobuf.Examples.AddressBook {
       return new AddressBook(this);
     }
 
+    /// <summary>Field number for the "people" field.</summary>
     public const int PeopleFieldNumber = 1;
     private static readonly pb::FieldCodec<global::Google.Protobuf.Examples.AddressBook.Person> _repeated_people_codec
         = pb::FieldCodec.ForMessage(10, global::Google.Protobuf.Examples.AddressBook.Person.Parser);

csharp/src/Google.Protobuf.Test/TestProtos/UnittestImportProto3.cs

@@ -78,6 +78,7 @@ namespace Google.Protobuf.TestProtos {
       return new ImportMessage(this);
     }
 
+    /// <summary>Field number for the "d" field.</summary>
     public const int DFieldNumber = 1;
     private int d_;
     public int D {

csharp/src/Google.Protobuf.Test/TestProtos/UnittestImportPublicProto3.cs

@@ -64,6 +64,7 @@ namespace Google.Protobuf.TestProtos {
       return new PublicImportMessage(this);
     }
 
+    /// <summary>Field number for the "e" field.</summary>
     public const int EFieldNumber = 1;
     private int e_;
     public int E {

csharp/src/Google.Protobuf.Test/TestProtos/UnittestIssues.cs

@@ -76,6 +76,10 @@ namespace UnitTest.Issues.TestProtos {
   #endregion
 
   #region Messages
+  /// <summary>
+  ///  Issue 307: when generating doubly-nested types, any references
+  ///  should be of the form A.Types.B.Types.C.
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class Issue307 : pb::IMessage<Issue307> {
     private static readonly pb::MessageParser<Issue307> _parser = new pb::MessageParser<Issue307>(() => new Issue307());
@@ -347,6 +351,7 @@ namespace UnitTest.Issues.TestProtos {
       return new NegativeEnumMessage(this);
     }
 
+    /// <summary>Field number for the "value" field.</summary>
     public const int ValueFieldNumber = 1;
     private global::UnitTest.Issues.TestProtos.NegativeEnum value_ = global::UnitTest.Issues.TestProtos.NegativeEnum.NEGATIVE_ENUM_ZERO;
     public global::UnitTest.Issues.TestProtos.NegativeEnum Value {
@@ -356,6 +361,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "values" field.</summary>
     public const int ValuesFieldNumber = 2;
     private static readonly pb::FieldCodec<global::UnitTest.Issues.TestProtos.NegativeEnum> _repeated_values_codec
         = pb::FieldCodec.ForEnum(16, x => (int) x, x => (global::UnitTest.Issues.TestProtos.NegativeEnum) x);
@@ -364,6 +370,7 @@ namespace UnitTest.Issues.TestProtos {
       get { return values_; }
     }
 
+    /// <summary>Field number for the "packed_values" field.</summary>
     public const int PackedValuesFieldNumber = 3;
     private static readonly pb::FieldCodec<global::UnitTest.Issues.TestProtos.NegativeEnum> _repeated_packedValues_codec
         = pb::FieldCodec.ForEnum(26, x => (int) x, x => (global::UnitTest.Issues.TestProtos.NegativeEnum) x);
@@ -566,6 +573,7 @@ namespace UnitTest.Issues.TestProtos {
       return new DeprecatedFieldsMessage(this);
     }
 
+    /// <summary>Field number for the "PrimitiveValue" field.</summary>
     public const int PrimitiveValueFieldNumber = 1;
     private int primitiveValue_;
     [global::System.ObsoleteAttribute()]
@@ -576,6 +584,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "PrimitiveArray" field.</summary>
     public const int PrimitiveArrayFieldNumber = 2;
     private static readonly pb::FieldCodec<int> _repeated_primitiveArray_codec
         = pb::FieldCodec.ForInt32(18);
@@ -585,6 +594,7 @@ namespace UnitTest.Issues.TestProtos {
       get { return primitiveArray_; }
     }
 
+    /// <summary>Field number for the "MessageValue" field.</summary>
     public const int MessageValueFieldNumber = 3;
     private global::UnitTest.Issues.TestProtos.DeprecatedChild messageValue_;
     [global::System.ObsoleteAttribute()]
@@ -595,6 +605,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "MessageArray" field.</summary>
     public const int MessageArrayFieldNumber = 4;
     private static readonly pb::FieldCodec<global::UnitTest.Issues.TestProtos.DeprecatedChild> _repeated_messageArray_codec
         = pb::FieldCodec.ForMessage(34, global::UnitTest.Issues.TestProtos.DeprecatedChild.Parser);
@@ -604,6 +615,7 @@ namespace UnitTest.Issues.TestProtos {
       get { return messageArray_; }
     }
 
+    /// <summary>Field number for the "EnumValue" field.</summary>
     public const int EnumValueFieldNumber = 5;
     private global::UnitTest.Issues.TestProtos.DeprecatedEnum enumValue_ = global::UnitTest.Issues.TestProtos.DeprecatedEnum.DEPRECATED_ZERO;
     [global::System.ObsoleteAttribute()]
@@ -614,6 +626,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "EnumArray" field.</summary>
     public const int EnumArrayFieldNumber = 6;
     private static readonly pb::FieldCodec<global::UnitTest.Issues.TestProtos.DeprecatedEnum> _repeated_enumArray_codec
         = pb::FieldCodec.ForEnum(50, x => (int) x, x => (global::UnitTest.Issues.TestProtos.DeprecatedEnum) x);
@@ -756,6 +769,9 @@ namespace UnitTest.Issues.TestProtos {
 
   }
 
+  /// <summary>
+  ///  Issue 45: http://code.google.com/p/protobuf-csharp-port/issues/detail?id=45
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class ItemField : pb::IMessage<ItemField> {
     private static readonly pb::MessageParser<ItemField> _parser = new pb::MessageParser<ItemField>(() => new ItemField());
@@ -783,6 +799,7 @@ namespace UnitTest.Issues.TestProtos {
       return new ItemField(this);
     }
 
+    /// <summary>Field number for the "item" field.</summary>
     public const int ItemFieldNumber = 1;
     private int item_;
     public int Item {
@@ -886,6 +903,7 @@ namespace UnitTest.Issues.TestProtos {
       return new ReservedNames(this);
     }
 
+    /// <summary>Field number for the "types" field.</summary>
     public const int Types_FieldNumber = 1;
     private int types_;
     public int Types_ {
@@ -895,6 +913,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "descriptor" field.</summary>
     public const int Descriptor_FieldNumber = 2;
     private int descriptor_;
     public int Descriptor_ {
@@ -988,6 +1007,9 @@ namespace UnitTest.Issues.TestProtos {
     /// <summary>Container for nested types declared in the ReservedNames message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
+      /// <summary>
+      ///  Force a nested type called Types
+      /// </summary>
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
       public sealed partial class SomeNestedType : pb::IMessage<SomeNestedType> {
         private static readonly pb::MessageParser<SomeNestedType> _parser = new pb::MessageParser<SomeNestedType>(() => new SomeNestedType());
@@ -1069,6 +1091,18 @@ namespace UnitTest.Issues.TestProtos {
 
   }
 
+  /// <summary>
+  ///  These fields are deliberately not declared in numeric
+  ///  order, and the oneof fields aren't contiguous either.
+  ///  This allows for reasonably robust tests of JSON output
+  ///  ordering.
+  ///  TestFieldOrderings in unittest_proto3.proto is similar,
+  ///  but doesn't include oneofs.
+  ///  TODO: Consider adding oneofs to TestFieldOrderings, although
+  ///  that will require fixing other tests in multiple platforms.
+  ///  Alternatively, consider just adding this to
+  ///  unittest_proto3.proto if multiple platforms want it.
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class TestJsonFieldOrdering : pb::IMessage<TestJsonFieldOrdering> {
     private static readonly pb::MessageParser<TestJsonFieldOrdering> _parser = new pb::MessageParser<TestJsonFieldOrdering>(() => new TestJsonFieldOrdering());
@@ -1115,6 +1149,7 @@ namespace UnitTest.Issues.TestProtos {
       return new TestJsonFieldOrdering(this);
     }
 
+    /// <summary>Field number for the "plain_int32" field.</summary>
     public const int PlainInt32FieldNumber = 4;
     private int plainInt32_;
     public int PlainInt32 {
@@ -1124,6 +1159,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "o1_string" field.</summary>
     public const int O1StringFieldNumber = 2;
     public string O1String {
       get { return o1Case_ == O1OneofCase.O1String ? (string) o1_ : ""; }
@@ -1133,6 +1169,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "o1_int32" field.</summary>
     public const int O1Int32FieldNumber = 5;
     public int O1Int32 {
       get { return o1Case_ == O1OneofCase.O1Int32 ? (int) o1_ : 0; }
@@ -1142,6 +1179,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "plain_string" field.</summary>
     public const int PlainStringFieldNumber = 1;
     private string plainString_ = "";
     public string PlainString {
@@ -1151,6 +1189,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "o2_int32" field.</summary>
     public const int O2Int32FieldNumber = 6;
     public int O2Int32 {
       get { return o2Case_ == O2OneofCase.O2Int32 ? (int) o2_ : 0; }
@@ -1160,6 +1199,7 @@ namespace UnitTest.Issues.TestProtos {
       }
     }
 
+    /// <summary>Field number for the "o2_string" field.</summary>
     public const int O2StringFieldNumber = 3;
     public string O2String {
       get { return o2Case_ == O2OneofCase.O2String ? (string) o2_ : ""; }

csharp/src/Google.Protobuf/WellKnownTypes/Any.cs

@@ -40,6 +40,33 @@ namespace Google.Protobuf.WellKnownTypes {
     }
   }
   #region Messages
+  /// <summary>
+  ///  `Any` contains an arbitrary serialized message along with a URL
+  ///  that describes the type of the serialized message.
+  ///  JSON
+  ///  ====
+  ///  The JSON representation of an `Any` value uses the regular
+  ///  representation of the deserialized, embedded message, with an
+  ///  additional field `@type` which contains the type URL. Example:
+  ///      package google.profile;
+  ///      message Person {
+  ///        string first_name = 1;
+  ///        string last_name = 2;
+  ///      }
+  ///      {
+  ///        "@type": "type.googleapis.com/google.profile.Person",
+  ///        "firstName": &lt;string>,
+  ///        "lastName": &lt;string>
+  ///      }
+  ///  If the embedded message type is well-known and has a custom JSON
+  ///  representation, that representation will be embedded adding a field
+  ///  `value` which holds the custom JSON in addition to the the `@type`
+  ///  field. Example (for message [google.protobuf.Duration][google.protobuf.Duration]):
+  ///      {
+  ///        "@type": "type.googleapis.com/google.protobuf.Duration",
+  ///        "value": "1.212s"
+  ///      }
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class Any : pb::IMessage<Any> {
     private static readonly pb::MessageParser<Any> _parser = new pb::MessageParser<Any>(() => new Any());
@@ -68,8 +95,27 @@ namespace Google.Protobuf.WellKnownTypes {
       return new Any(this);
     }
 
+    /// <summary>Field number for the "type_url" field.</summary>
     public const int TypeUrlFieldNumber = 1;
     private string typeUrl_ = "";
+    /// <summary>
+    ///  A URL/resource name whose content describes the type of the
+    ///  serialized message.
+    ///  For URLs which use the schema `http`, `https`, or no schema, the
+    ///  following restrictions and interpretations apply:
+    ///  * If no schema is provided, `https` is assumed.
+    ///  * The last segment of the URL's path must represent the fully
+    ///    qualified name of the type (as in `path/google.protobuf.Duration`).
+    ///  * An HTTP GET on the URL must yield a [google.protobuf.Type][google.protobuf.Type]
+    ///    value in binary format, or produce an error.
+    ///  * Applications are allowed to cache lookup results based on the
+    ///    URL, or have them precompiled into a binary to avoid any
+    ///    lookup. Therefore, binary compatibility needs to be preserved
+    ///    on changes to types. (Use versioned type names to manage
+    ///    breaking changes.)
+    ///  Schemas other than `http`, `https` (or the empty schema) might be
+    ///  used with implementation specific semantics.
+    /// </summary>
     public string TypeUrl {
       get { return typeUrl_; }
       set {
@@ -77,8 +123,12 @@ namespace Google.Protobuf.WellKnownTypes {
       }
     }
 
+    /// <summary>Field number for the "value" field.</summary>
     public const int ValueFieldNumber = 2;
     private pb::ByteString value_ = pb::ByteString.Empty;
+    /// <summary>
+    ///  Must be valid serialized data of the above specified type.
+    /// </summary>
     public pb::ByteString Value {
       get { return value_; }
       set {

csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs

@@ -41,6 +41,40 @@ namespace Google.Protobuf.WellKnownTypes {
     }
   }
   #region Messages
+  /// <summary>
+  ///  A Duration represents a signed, fixed-length span of time represented
+  ///  as a count of seconds and fractions of seconds at nanosecond
+  ///  resolution. It is independent of any calendar and concepts like "day"
+  ///  or "month". It is related to Timestamp in that the difference between
+  ///  two Timestamp values is a Duration and it can be added or subtracted
+  ///  from a Timestamp. Range is approximately +-10,000 years.
+  ///  Example 1: Compute Duration from two Timestamps in pseudo code.
+  ///      Timestamp start = ...;
+  ///      Timestamp end = ...;
+  ///      Duration duration = ...;
+  ///      duration.seconds = end.seconds - start.seconds;
+  ///      duration.nanos = end.nanos - start.nanos;
+  ///      if (duration.seconds &lt; 0 &amp;&amp; duration.nanos > 0) {
+  ///        duration.seconds += 1;
+  ///        duration.nanos -= 1000000000;
+  ///      } else if (durations.seconds > 0 &amp;&amp; duration.nanos &lt; 0) {
+  ///        duration.seconds -= 1;
+  ///        duration.nanos += 1000000000;
+  ///      }
+  ///  Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
+  ///      Timestamp start = ...;
+  ///      Duration duration = ...;
+  ///      Timestamp end = ...;
+  ///      end.seconds = start.seconds + duration.seconds;
+  ///      end.nanos = start.nanos + duration.nanos;
+  ///      if (end.nanos &lt; 0) {
+  ///        end.seconds -= 1;
+  ///        end.nanos += 1000000000;
+  ///      } else if (end.nanos >= 1000000000) {
+  ///        end.seconds += 1;
+  ///        end.nanos -= 1000000000;
+  ///      }
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class Duration : pb::IMessage<Duration> {
     private static readonly pb::MessageParser<Duration> _parser = new pb::MessageParser<Duration>(() => new Duration());
@@ -69,8 +103,13 @@ namespace Google.Protobuf.WellKnownTypes {
       return new Duration(this);
     }
 
+    /// <summary>Field number for the "seconds" field.</summary>
     public const int SecondsFieldNumber = 1;
     private long seconds_;
+    /// <summary>
+    ///  Signed seconds of the span of time. Must be from -315,576,000,000
+    ///  to +315,576,000,000 inclusive.
+    /// </summary>
     public long Seconds {
       get { return seconds_; }
       set {
@@ -78,8 +117,17 @@ namespace Google.Protobuf.WellKnownTypes {
       }
     }
 
+    /// <summary>Field number for the "nanos" field.</summary>
     public const int NanosFieldNumber = 2;
     private int nanos_;
+    /// <summary>
+    ///  Signed fractions of a second at nanosecond resolution of the span
+    ///  of time. Durations less than one second are represented with a 0
+    ///  `seconds` field and a positive or negative `nanos` field. For durations
+    ///  of one second or more, a non-zero value for the `nanos` field must be
+    ///  of the same sign as the `seconds` field. Must be from -999,999,999
+    ///  to +999,999,999 inclusive.
+    /// </summary>
     public int Nanos {
       get { return nanos_; }
       set {

csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs

@@ -40,6 +40,15 @@ namespace Google.Protobuf.WellKnownTypes {
     }
   }
   #region Messages
+  /// <summary>
+  ///  A generic empty message that you can re-use to avoid defining duplicated
+  ///  empty messages in your APIs. A typical example is to use it as the request
+  ///  or the response type of an API method. For instance:
+  ///      service Foo {
+  ///        rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
+  ///      }
+  ///  The JSON representation for `Empty` is empty JSON object `{}`.
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class Empty : pb::IMessage<Empty> {
     private static readonly pb::MessageParser<Empty> _parser = new pb::MessageParser<Empty>(() => new Empty());

csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs

@@ -40,6 +40,103 @@ namespace Google.Protobuf.WellKnownTypes {
     }
   }
   #region Messages
+  /// <summary>
+  ///  `FieldMask` represents a set of symbolic field paths, for example:
+  ///      paths: "f.a"
+  ///      paths: "f.b.d"
+  ///  Here `f` represents a field in some root message, `a` and `b`
+  ///  fields in the message found in `f`, and `d` a field found in the
+  ///  message in `f.b`.
+  ///  Field masks are used to specify a subset of fields that should be
+  ///  returned by a get operation or modified by an update operation.
+  ///  Field masks also have a custom JSON encoding (see below).
+  ///  # Field Masks in Projections
+  ///  When used in the context of a projection, a response message or
+  ///  sub-message is filtered by the API to only contain those fields as
+  ///  specified in the mask. For example, if the mask in the previous
+  ///  example is applied to a response message as follows:
+  ///      f {
+  ///        a : 22
+  ///        b {
+  ///          d : 1
+  ///          x : 2
+  ///        }
+  ///        y : 13
+  ///      }
+  ///      z: 8
+  ///  The result will not contain specific values for fields x,y and z
+  ///  (there value will be set to the default, and omitted in proto text
+  ///  output):
+  ///      f {
+  ///        a : 22
+  ///        b {
+  ///          d : 1
+  ///        }
+  ///      }
+  ///  A repeated field is not allowed except at the last position of a
+  ///  field mask.
+  ///  If a FieldMask object is not present in a get operation, the
+  ///  operation applies to all fields (as if a FieldMask of all fields
+  ///  had been specified).
+  ///  Note that a field mask does not necessarily applies to the
+  ///  top-level response message. In case of a REST get operation, the
+  ///  field mask applies directly to the response, but in case of a REST
+  ///  list operation, the mask instead applies to each individual message
+  ///  in the returned resource list. In case of a REST custom method,
+  ///  other definitions may be used. Where the mask applies will be
+  ///  clearly documented together with its declaration in the API.  In
+  ///  any case, the effect on the returned resource/resources is required
+  ///  behavior for APIs.
+  ///  # Field Masks in Update Operations
+  ///  A field mask in update operations specifies which fields of the
+  ///  targeted resource are going to be updated. The API is required
+  ///  to only change the values of the fields as specified in the mask
+  ///  and leave the others untouched. If a resource is passed in to
+  ///  describe the updated values, the API ignores the values of all
+  ///  fields not covered by the mask.
+  ///  In order to reset a field's value to the default, the field must
+  ///  be in the mask and set to the default value in the provided resource.
+  ///  Hence, in order to reset all fields of a resource, provide a default
+  ///  instance of the resource and set all fields in the mask, or do
+  ///  not provide a mask as described below.
+  ///  If a field mask is not present on update, the operation applies to
+  ///  all fields (as if a field mask of all fields has been specified).
+  ///  Note that in the presence of schema evolution, this may mean that
+  ///  fields the client does not know and has therefore not filled into
+  ///  the request will be reset to their default. If this is unwanted
+  ///  behavior, a specific service may require a client to always specify
+  ///  a field mask, producing an error if not.
+  ///  As with get operations, the location of the resource which
+  ///  describes the updated values in the request message depends on the
+  ///  operation kind. In any case, the effect of the field mask is
+  ///  required to be honored by the API.
+  ///  ## Considerations for HTTP REST
+  ///  The HTTP kind of an update operation which uses a field mask must
+  ///  be set to PATCH instead of PUT in order to satisfy HTTP semantics
+  ///  (PUT must only be used for full updates).
+  ///  # JSON Encoding of Field Masks
+  ///  In JSON, a field mask is encoded as a single string where paths are
+  ///  separated by a comma. Fields name in each path are converted
+  ///  to/from lower-camel naming conventions.
+  ///  As an example, consider the following message declarations:
+  ///      message Profile {
+  ///        User user = 1;
+  ///        Photo photo = 2;
+  ///      }
+  ///      message User {
+  ///        string display_name = 1;
+  ///        string address = 2;
+  ///      }
+  ///  In proto a field mask for `Profile` may look as such:
+  ///      mask {
+  ///        paths: "user.display_name"
+  ///        paths: "photo"
+  ///      }
+  ///  In JSON, the same mask is represented as below:
+  ///      {
+  ///        mask: "user.displayName,photo"
+  ///      }
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class FieldMask : pb::IMessage<FieldMask> {
     private static readonly pb::MessageParser<FieldMask> _parser = new pb::MessageParser<FieldMask>(() => new FieldMask());
@@ -67,10 +164,14 @@ namespace Google.Protobuf.WellKnownTypes {
       return new FieldMask(this);
     }
 
+    /// <summary>Field number for the "paths" field.</summary>
     public const int PathsFieldNumber = 1;
     private static readonly pb::FieldCodec<string> _repeated_paths_codec
         = pb::FieldCodec.ForString(10);
     private readonly pbc::RepeatedField<string> paths_ = new pbc::RepeatedField<string>();
+    /// <summary>
+    ///  The set of field mask paths.
+    /// </summary>
     public pbc::RepeatedField<string> Paths {
       get { return paths_; }
     }

csharp/src/Google.Protobuf/WellKnownTypes/SourceContext.cs

@@ -41,6 +41,10 @@ namespace Google.Protobuf.WellKnownTypes {
     }
   }
   #region Messages
+  /// <summary>
+  ///  `SourceContext` represents information about the source of a
+  ///  protobuf element, like the file in which it is defined.
+  /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public sealed partial class SourceContext : pb::IMessage<SourceContext> {
     private static readonly pb::MessageParser<SourceContext> _parser = new pb::MessageParser<SourceContext>(() => new SourceContext());
@@ -68,8 +72,13 @@ namespace Google.Protobuf.WellKnownTypes {
       return new SourceContext(this);
     }
 
+    /// <summary>Field number for the "file_name" field.</summary>
     public const int FileNameFieldNumber = 1;
     private string fileName_ = "";
+    /// <summary>
+    ///  The path-qualified name of the .proto file that contained the associated
+    ///  protobuf element.  For example: `"google/protobuf/source.proto"`.
+    /// </summary>
     public string FileName {
       get { return fileName_; }
       set {

src/Makefile.am

@@ -434,6 +434,8 @@ libprotoc_la_SOURCES =                                         \
   google/protobuf/compiler/objectivec/objectivec_primitive_field.h \
   google/protobuf/compiler/python/python_generator.cc          \
   google/protobuf/compiler/ruby/ruby_generator.cc              \
+  google/protobuf/compiler/csharp/csharp_doc_comment.cc        \
+  google/protobuf/compiler/csharp/csharp_doc_comment.h         \
   google/protobuf/compiler/csharp/csharp_enum.cc               \
   google/protobuf/compiler/csharp/csharp_enum.h                \
   google/protobuf/compiler/csharp/csharp_enum_field.cc         \

src/google/protobuf/compiler/csharp/csharp_enum.cc

@@ -38,6 +38,7 @@
 #include <google/protobuf/io/zero_copy_stream.h>
 #include <google/protobuf/stubs/strutil.h>
 
+#include <google/protobuf/compiler/csharp/csharp_doc_comment.h>
 #include <google/protobuf/compiler/csharp/csharp_enum.h>
 #include <google/protobuf/compiler/csharp/csharp_helpers.h>
 
@@ -57,13 +58,15 @@ EnumGenerator::~EnumGenerator() {
 }
 
 void EnumGenerator::Generate(io::Printer* printer) {
+  WriteEnumDocComment(printer, descriptor_);
   WriteGeneratedCodeAttributes(printer);
   printer->Print("$access_level$ enum $name$ {\n",
                  "access_level", class_access_level(),
                  "name", descriptor_->name());
   printer->Indent();
   for (int i = 0; i < descriptor_->value_count(); i++) {
-    printer->Print("$name$ = $number$,\n",
+      WriteEnumValueDocComment(printer, descriptor_->value(i));
+      printer->Print("$name$ = $number$,\n",
                    "name", descriptor_->value(i)->name(),
                    "number", SimpleItoa(descriptor_->value(i)->number()));
   }

src/google/protobuf/compiler/csharp/csharp_map_field.cc

@@ -38,6 +38,7 @@
 #include <google/protobuf/io/zero_copy_stream.h>
 #include <google/protobuf/stubs/strutil.h>
 
+#include <google/protobuf/compiler/csharp/csharp_doc_comment.h>
 #include <google/protobuf/compiler/csharp/csharp_helpers.h>
 #include <google/protobuf/compiler/csharp/csharp_map_field.h>
 
@@ -76,6 +77,7 @@ void MapFieldGenerator::GenerateMembers(io::Printer* printer) {
     variables_,
     ", $tag$);\n"
     "private readonly pbc::MapField<$key_type_name$, $value_type_name$> $name$_ = new pbc::MapField<$key_type_name$, $value_type_name$>($true_for_wrappers$);\n");
+  WritePropertyDocComment(printer, descriptor_);
   AddDeprecatedFlag(printer);
   printer->Print(
     variables_,