AuroraMiddleware/protobuf
1
0
Fork 0
Code Issues 1 Pull Requests Projects Releases Wiki Activity

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

Browse Source 
Stop removing all blank lines in doc comments.
This commit is contained in:
Jan Tattermusch 2015-11-08 19:17:08 -08:00
commit 64aa954dae
11 changed files with 133 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
csharp/src/Google.Protobuf.Conformance/Conformance.cs
View File

@ -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>

25
csharp/src/Google.Protobuf/Reflection/DescriptorProtoFile.cs
View File

@ -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 {

8
csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
View File

@ -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>

18
csharp/src/Google.Protobuf/WellKnownTypes/Api.cs
View File

@ -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) {

8
csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs
View File

@ -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;

2
csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs
View File

@ -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()]

26
csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs
View File

@ -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"
/// }

4
csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs
View File

@ -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()]

13
csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
View File

@ -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)

9
csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs
View File

@ -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()]

20
src/google/protobuf/compiler/csharp/csharp_doc_comment.cc
View File

@ -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");
}