Merge pull request #954 from jskeet/blank-lines-in-comments

Stop removing all blank lines in doc comments.

11 files changed, 133 insertions, 2 deletions

diff --git a/csharp/src/Google.Protobuf.Conformance/Conformance.cs b/csharp/src/Google.Protobuf.Conformance/Conformance.cs
index 9626bea3..3ebaa4ef 100644
--- a/csharp/src/Google.Protobuf.Conformance/Conformance.cs
+++ b/csharp/src/Google.Protobuf.Conformance/Conformance.cs
@@ -165,6 +165,7 @@ namespace Conformance {
   #region Messages
   /// <summary>
   ///  Represents a single test case's input.  The testee should:
+  ///
   ///    1. parse this proto (which should always succeed)
   ///    2. parse the protobuf or JSON payload in "payload" (which may fail)
   ///    3. if the parse succeeded, serialize the message in the requested format.
@@ -410,6 +411,7 @@ namespace Conformance {
     /// <summary>
     ///  This string should be set to indicate parsing failed.  The string can
     ///  provide more information about the parse error if it is available.
+    ///
     ///  Setting this string does not necessarily mean the testee failed the
     ///  test.  Some of the test cases are intentionally invalid input.
     /// </summary>
diff --git a/csharp/src/Google.Protobuf/Reflection/DescriptorProtoFile.cs b/csharp/src/Google.Protobuf/Reflection/DescriptorProtoFile.cs
index ee43bec2..25a03538 100644
--- a/csharp/src/Google.Protobuf/Reflection/DescriptorProtoFile.cs
+++ b/csharp/src/Google.Protobuf/Reflection/DescriptorProtoFile.cs
@@ -2695,6 +2695,7 @@ namespace Google.Protobuf.Reflection {
     ///  main code generators in each language (without additional plugins).
     ///  Generic services were the only kind of service generation supported by
     ///  early versions of google.protobuf.
+    ///
     ///  Generic services are now considered deprecated in favor of using plugins
     ///  that generate code specific to your particular RPC system.  Therefore,
     ///  these default to false.  Old code which depends on generic services should
@@ -3173,6 +3174,7 @@ namespace Google.Protobuf.Reflection {
     ///  This is provided for backwards-compatibility with the MessageSet wire
     ///  format.  You should not use this for any other reason:  It's less
     ///  efficient, has fewer features, and is more complicated.
+    ///
     ///  The message must be defined exactly as follows:
     ///    message Foo {
     ///      option message_set_wire_format = true;
@@ -3180,8 +3182,10 @@ namespace Google.Protobuf.Reflection {
     ///    }
     ///  Note that the message cannot have any defined fields; MessageSets only
     ///  have extensions.
+    ///
     ///  All extensions of your type must be singular messages; e.g. they cannot
     ///  be int32s, enums, or repeated messages.
+    ///
     ///  Because this is an option, the above two restrictions are not enforced by
     ///  the protocol compiler.
     /// </summary>
@@ -3229,6 +3233,7 @@ namespace Google.Protobuf.Reflection {
     /// <summary>
     ///  Whether the message is an automatically generated map entry type for the
     ///  maps field.
+    ///
     ///  For maps fields:
     ///      map&lt;KeyType, ValueType> map_field = 1;
     ///  The parsed descriptor looks like:
@@ -3238,10 +3243,12 @@ namespace Google.Protobuf.Reflection {
     ///          optional ValueType value = 2;
     ///      }
     ///      repeated MapFieldEntry map_field = 1;
+    ///
     ///  Implementations may choose not to generate the map_entry=true message, but
     ///  use a native map in the target language to hold the keys and values.
     ///  The reflection APIs in such implementions still need to work as
     ///  if the field is a repeated message field.
+    ///
     ///  NOTE: Do not set the option in .proto files. Always use the maps syntax
     ///  instead. The option should only be implicitly set by the proto compiler
     ///  parser.
@@ -3483,16 +3490,19 @@ namespace Google.Protobuf.Reflection {
     ///  fields.  It means that when the outer message is initially parsed, the
     ///  inner message's contents will not be parsed but instead stored in encoded
     ///  form.  The inner message will actually be parsed when it is first accessed.
+    ///
     ///  This is only a hint.  Implementations are free to choose whether to use
     ///  eager or lazy parsing regardless of the value of this option.  However,
     ///  setting this option true suggests that the protocol author believes that
     ///  using lazy parsing on this field is worth the additional bookkeeping
     ///  overhead typically needed to implement it.
+    ///
     ///  This option does not affect the public interface of any generated code;
     ///  all method signatures remain the same.  Furthermore, thread-safety of the
     ///  interface is not affected by this option; const methods remain safe to
     ///  call from multiple threads concurrently, while non-const methods continue
     ///  to require exclusive access.
+    ///
     ///  Note that implementations may choose not to check required fields within
     ///  a lazy sub-message.  That is, calling IsInitialized() on the outher message
     ///  may return true even if the inner message has missing required fields.
@@ -4747,6 +4757,7 @@ namespace Google.Protobuf.Reflection {
     ///  corresponds to a particular definition.  This information is intended
     ///  to be useful to IDEs, code indexers, documentation generators, and similar
     ///  tools.
+    ///
     ///  For example, say we have a file like:
     ///    message Foo {
     ///      optional string foo = 1;
@@ -4762,6 +4773,7 @@ namespace Google.Protobuf.Reflection {
     ///    [c,d)  [ 4, 0, 2, 0, 5 ]  The type (string).
     ///    [e,f)  [ 4, 0, 2, 0, 1 ]  The name (foo).
     ///    [g,h)  [ 4, 0, 2, 0, 3 ]  The number (1).
+    ///
     ///  Notes:
     ///  - A location may refer to a repeated field itself (i.e. not to any
     ///    particular index within it).  This is used whenever a set of elements are
@@ -4889,6 +4901,7 @@ namespace Google.Protobuf.Reflection {
         /// <summary>
         ///  Identifies which part of the FileDescriptorProto was defined at this
         ///  location.
+        ///
         ///  Each element is a field number or an index.  They form a path from
         ///  the root FileDescriptorProto to the place where the definition.  For
         ///  example, this path:
@@ -4903,6 +4916,7 @@ namespace Google.Protobuf.Reflection {
         ///    repeated FieldDescriptorProto field = 2;
         ///  and FieldDescriptorProto.name has field number 1:
         ///    optional string name = 1;
+        ///
         ///  Thus, the above path gives the location of a field name.  If we removed
         ///  the last element:
         ///    [ 4, 3, 2, 7 ]
@@ -4936,31 +4950,41 @@ namespace Google.Protobuf.Reflection {
         ///  If this SourceCodeInfo represents a complete declaration, these are any
         ///  comments appearing before and after the declaration which appear to be
         ///  attached to the declaration.
+        ///
         ///  A series of line comments appearing on consecutive lines, with no other
         ///  tokens appearing on those lines, will be treated as a single comment.
+        ///
         ///  leading_detached_comments will keep paragraphs of comments that appear
         ///  before (but not connected to) the current element. Each paragraph,
         ///  separated by empty lines, will be one comment element in the repeated
         ///  field.
+        ///
         ///  Only the comment content is provided; comment markers (e.g. //) are
         ///  stripped out.  For block comments, leading whitespace and an asterisk
         ///  will be stripped from the beginning of each line other than the first.
         ///  Newlines are included in the output.
+        ///
         ///  Examples:
+        ///
         ///    optional int32 foo = 1;  // Comment attached to foo.
         ///    // Comment attached to bar.
         ///    optional int32 bar = 2;
+        ///
         ///    optional string baz = 3;
         ///    // Comment attached to baz.
         ///    // Another line attached to baz.
+        ///
         ///    // Comment attached to qux.
         ///    //
         ///    // Another line attached to qux.
         ///    optional double qux = 4;
+        ///
         ///    // Detached comment for corge. This is not leading or trailing comments
         ///    // to qux or corge because there are blank lines separating it from
         ///    // both.
+        ///
         ///    // Detached comment for corge paragraph 2.
+        ///
         ///    optional string corge = 5;
         ///    /* Block comment attached
         ///     * to corge.  Leading asterisks
@@ -4968,6 +4992,7 @@ namespace Google.Protobuf.Reflection {
         ///    /* Block comment attached to
         ///     * grault. */
         ///    optional int32 grault = 6;
+        ///
         ///    // ignored detached comments.
         /// </summary>
         public string LeadingComments {
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
index 4a704018..64cbd33d 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
@@ -43,25 +43,30 @@ namespace Google.Protobuf.WellKnownTypes {
   /// <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"
@@ -101,8 +106,10 @@ namespace Google.Protobuf.WellKnownTypes {
     /// <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`).
@@ -113,6 +120,7 @@ namespace Google.Protobuf.WellKnownTypes {
     ///    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>
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs
index 2c64314d..899613f9 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs
@@ -139,12 +139,14 @@ namespace Google.Protobuf.WellKnownTypes {
     ///  outlined below. If the field is not empty, the version in the
     ///  package name will be verified to be consistent with what is
     ///  provided here.
+    ///
     ///  The versioning schema uses [semantic
     ///  versioning](http://semver.org) where the major version number
     ///  indicates a breaking change and the minor version an additive,
     ///  non-breaking change. Both version numbers are signals to users
     ///  what to expect from different versions, and should be carefully
     ///  chosen based on the product plan.
+    ///
     ///  The major version is also reflected in the package name of the
     ///  API, which must end in `v&lt;major-version>`, as in
     ///  `google.feature.v1`. For major versions 0 and 1, the suffix can
@@ -629,16 +631,21 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  Declares an API to be included in this API. The including API must
   ///  redeclare all the methods from the included API, but documentation
   ///  and options are inherited as follows:
+  ///
   ///  - If after comment and whitespace stripping, the documentation
   ///    string of the redeclared method is empty, it will be inherited
   ///    from the original method.
+  ///
   ///  - Each annotation belonging to the service config (http,
   ///    visibility) which is not set in the redeclared method will be
   ///    inherited.
+  ///
   ///  - If an http annotation is inherited, the path pattern will be
   ///    modified as follows. Any version prefix will be replaced by the
   ///    version of the including API plus the [root][] path if specified.
+  ///
   ///  Example of a simple mixin:
+  ///
   ///      package google.acl.v1;
   ///      service AccessControl {
   ///        // Get the underlying ACL object.
@@ -646,25 +653,31 @@ namespace Google.Protobuf.WellKnownTypes {
   ///          option (google.api.http).get = "/v1/{resource=**}:getAcl";
   ///        }
   ///      }
+  ///
   ///      package google.storage.v2;
   ///      service Storage {
   ///        // (-- see AccessControl.GetAcl --)
   ///        rpc GetAcl(GetAclRequest) returns (Acl);
+  ///
   ///        // Get a data record.
   ///        rpc GetData(GetDataRequest) returns (Data) {
   ///          option (google.api.http).get = "/v2/{resource=**}";
   ///        }
   ///      }
+  ///
   ///  Example of a mixin configuration:
+  ///
   ///      apis:
   ///      - name: google.storage.v2.Storage
   ///        mixins:
   ///        - name: google.acl.v1.AccessControl
+  ///
   ///  The mixin construct implies that all methods in `AccessControl` are
   ///  also declared with same name and request/response types in
   ///  `Storage`. A documentation generator or annotation processor will
   ///  see the effective `Storage.GetAcl` method after inherting
   ///  documentation and annotations as follows:
+  ///
   ///      service Storage {
   ///        // Get the underlying ACL object.
   ///        rpc GetAcl(GetAclRequest) returns (Acl) {
@@ -672,15 +685,20 @@ namespace Google.Protobuf.WellKnownTypes {
   ///        }
   ///        ...
   ///      }
+  ///
   ///  Note how the version in the path pattern changed from `v1` to `v2`.
+  ///
   ///  If the `root` field in the mixin is specified, it should be a
   ///  relative path under which inherited HTTP paths are placed. Example:
+  ///
   ///      apis:
   ///      - name: google.storage.v2.Storage
   ///        mixins:
   ///        - name: google.acl.v1.AccessControl
   ///          root: acls
+  ///
   ///  This implies the following inherited HTTP annotation:
+  ///
   ///      service Storage {
   ///        // Get the underlying ACL object.
   ///        rpc GetAcl(GetAclRequest) returns (Acl) {
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs
index 39251e2e..cc2dfd26 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs
@@ -48,12 +48,16 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  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;
@@ -61,12 +65,16 @@ namespace Google.Protobuf.WellKnownTypes {
   ///        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;
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs
index 18223a9e..f2d2de01 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs
@@ -44,9 +44,11 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  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()]
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
index 33c814ef..e71e4af6 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
@@ -42,19 +42,25 @@ 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 {
@@ -64,20 +70,25 @@ namespace Google.Protobuf.WellKnownTypes {
   ///        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
@@ -87,18 +98,22 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  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
@@ -106,19 +121,26 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  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;
@@ -127,12 +149,16 @@ namespace Google.Protobuf.WellKnownTypes {
   ///        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"
   ///      }
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs
index b2d7783c..8f8e917d 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs
@@ -55,6 +55,7 @@ namespace Google.Protobuf.WellKnownTypes {
   /// <summary>
   ///  `NullValue` is a singleton enumeration to represent the null value for the
   ///  `Value` type union.
+  ///
   ///   The JSON representation for `NullValue` is JSON `null`.
   /// </summary>
   public enum NullValue {
@@ -74,6 +75,7 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  scripting languages like JS a struct is represented as an
   ///  object. The details of that representation are described together
   ///  with the proto support for the language.
+  ///
   ///  The JSON representation for `Struct` is JSON object.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -179,6 +181,7 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  null, a number, a string, a boolean, a recursive struct value, or a
   ///  list of values. A producer of value is expected to set one of that
   ///  variants, absence of any variant indicates an error.
+  ///
   ///  The JSON representation for `Value` is JSON value.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -491,6 +494,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  `ListValue` is a wrapper around a repeated field of values.
+  ///
   ///  The JSON representation for `ListValue` is JSON array.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
index f372f8fd..1044a683 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
@@ -53,30 +53,43 @@ namespace Google.Protobuf.WellKnownTypes {
   ///  By restricting to that range, we ensure that we can convert to
   ///  and from  RFC 3339 date strings.
   ///  See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+  ///
   ///  Example 1: Compute Timestamp from POSIX `time()`.
+  ///
   ///      Timestamp timestamp;
   ///      timestamp.set_seconds(time(NULL));
   ///      timestamp.set_nanos(0);
+  ///
   ///  Example 2: Compute Timestamp from POSIX `gettimeofday()`.
+  ///
   ///      struct timeval tv;
   ///      gettimeofday(&amp;tv, NULL);
+  ///
   ///      Timestamp timestamp;
   ///      timestamp.set_seconds(tv.tv_sec);
   ///      timestamp.set_nanos(tv.tv_usec * 1000);
+  ///
   ///  Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
+  ///
   ///      FILETIME ft;
   ///      GetSystemTimeAsFileTime(&amp;ft);
   ///      UINT64 ticks = (((UINT64)ft.dwHighDateTime) &lt;&lt; 32) | ft.dwLowDateTime;
+  ///
   ///      // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
   ///      // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
   ///      Timestamp timestamp;
   ///      timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
   ///      timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
+  ///
   ///  Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
+  ///
   ///      long millis = System.currentTimeMillis();
+  ///
   ///      Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
   ///          .setNanos((int) ((millis % 1000) * 1000000)).build();
+  ///
   ///  Example 5: Compute Timestamp from current time in Python.
+  ///
   ///      now = time.time()
   ///      seconds = int(now)
   ///      nanos = int((now - seconds) * 10**9)
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs
index d26395f8..7fdcb11e 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs
@@ -52,6 +52,7 @@ namespace Google.Protobuf.WellKnownTypes {
   #region Messages
   /// <summary>
   ///  Wrapper message for `double`.
+  ///
   ///  The JSON representation for `DoubleValue` is JSON number.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -162,6 +163,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `float`.
+  ///
   ///  The JSON representation for `FloatValue` is JSON number.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -272,6 +274,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `int64`.
+  ///
   ///  The JSON representation for `Int64Value` is JSON string.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -382,6 +385,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `uint64`.
+  ///
   ///  The JSON representation for `UInt64Value` is JSON string.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -492,6 +496,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `int32`.
+  ///
   ///  The JSON representation for `Int32Value` is JSON number.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -602,6 +607,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `uint32`.
+  ///
   ///  The JSON representation for `UInt32Value` is JSON number.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -712,6 +718,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `bool`.
+  ///
   ///  The JSON representation for `BoolValue` is JSON `true` and `false`.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -822,6 +829,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `string`.
+  ///
   ///  The JSON representation for `StringValue` is JSON string.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -932,6 +940,7 @@ namespace Google.Protobuf.WellKnownTypes {
 
   /// <summary>
   ///  Wrapper message for `bytes`.
+  ///
   ///  The JSON representation for `BytesValue` is JSON string.
   /// </summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
diff --git a/src/google/protobuf/compiler/csharp/csharp_doc_comment.cc b/src/google/protobuf/compiler/csharp/csharp_doc_comment.cc
index 9ad2cbb5..587e0222 100644
--- a/src/google/protobuf/compiler/csharp/csharp_doc_comment.cc
+++ b/src/google/protobuf/compiler/csharp/csharp_doc_comment.cc
@@ -56,10 +56,26 @@ void WriteDocCommentBodyImpl(io::Printer* printer, SourceLocation location) {
     // node of a summary element, not part of an attribute.
     comments = StringReplace(comments, "&", "&amp;", true);
     comments = StringReplace(comments, "<", "&lt;", true);
-    vector<string> lines = Split(comments, "\n");
+    vector<string> lines = Split(comments, "\n", false /* skip_empty */);
+    // TODO: We really should work out which part to put in the summary and which to put in the remarks...
+    // but that needs to be part of a bigger effort to understand the markdown better anyway.
     printer->Print("/// <summary>\n");
+    bool last_was_empty = false;
+    // We squash multiple blank lines down to one, and remove any trailing blank lines. We need
+    // to preserve the blank lines themselves, as this is relevant in the markdown.
+    // Note that we can't remove leading or trailing whitespace as *that's* relevant in markdown too.
+    // (We don't skip "just whitespace" lines, either.)
     for (std::vector<string>::iterator it = lines.begin(); it != lines.end(); ++it) {
-        printer->Print("/// $line$\n", "line", *it);
+        string line = *it;
+        if (line.empty()) {
+            last_was_empty = true;
+        } else {
+            if (last_was_empty) {
+                printer->Print("///\n");
+            }
+            last_was_empty = false;
+            printer->Print("/// $line$\n", "line", *it);
+        }
     }
     printer->Print("/// </summary>\n");
 }