diff options
author | Jan Tattermusch <jtattermusch@users.noreply.github.com> | 2015-11-08 19:17:08 -0800 |
---|---|---|
committer | Jan Tattermusch <jtattermusch@users.noreply.github.com> | 2015-11-08 19:17:08 -0800 |
commit | 64aa954daec2f6f2df460f9bcc1e2ca6ba42b640 (patch) | |
tree | 1516488c97abdffcf10dcd9f5b9c38b5f6eb1cc6 /csharp/src/Google.Protobuf/WellKnownTypes/Api.cs | |
parent | 1e54dcfc707bc6ba23ac9a087336836f95d7fbd0 (diff) | |
parent | cff900e8f9e4b8f3a8f314f0f44eab222ebb870b (diff) | |
download | protobuf-64aa954daec2f6f2df460f9bcc1e2ca6ba42b640.tar.gz protobuf-64aa954daec2f6f2df460f9bcc1e2ca6ba42b640.tar.bz2 protobuf-64aa954daec2f6f2df460f9bcc1e2ca6ba42b640.zip |
Merge pull request #954 from jskeet/blank-lines-in-comments
Stop removing all blank lines in doc comments.
Diffstat (limited to 'csharp/src/Google.Protobuf/WellKnownTypes/Api.cs')
-rw-r--r-- | csharp/src/Google.Protobuf/WellKnownTypes/Api.cs | 18 |
1 files changed, 18 insertions, 0 deletions
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<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) { |