aboutsummaryrefslogtreecommitdiff
path: root/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs
diff options
context:
space:
mode:
authorJon Skeet <jonskeet@google.com>2015-11-06 18:38:31 +0000
committerJon Skeet <jonskeet@google.com>2015-11-06 18:38:31 +0000
commitcff900e8f9e4b8f3a8f314f0f44eab222ebb870b (patch)
tree9bb37e2e6639faa7c020caaccc918e7f81ac844c /csharp/src/Google.Protobuf/WellKnownTypes/Api.cs
parentf4f601bd477e01c98d95dece5a694107205a8134 (diff)
downloadprotobuf-cff900e8f9e4b8f3a8f314f0f44eab222ebb870b.tar.gz
protobuf-cff900e8f9e4b8f3a8f314f0f44eab222ebb870b.tar.bz2
protobuf-cff900e8f9e4b8f3a8f314f0f44eab222ebb870b.zip
Generated code for previous commit.
Diffstat (limited to 'csharp/src/Google.Protobuf/WellKnownTypes/Api.cs')
-rw-r--r--csharp/src/Google.Protobuf/WellKnownTypes/Api.cs18
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&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) {