Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

TechDebitReduction: Cleanup some of the language in the documentation. #165

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

TechDebitReduction: Cleanup some of the language in the documentation. #165

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1dceb0f
TechDebitReduction: Cleanup some of the language in the documentation.
Jan 10, 2024
8244c2c
Address comments from hellt.
Jan 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 21 additions & 23 deletions proto/gnmi/gnmi.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ import "google/protobuf/descriptor.proto";
import "github.com/openconfig/gnmi/proto/gnmi_ext/gnmi_ext.proto";

// Package gNMI defines a service specification for the gRPC Network Management
// Interface. This interface is defined to be a standard interface via which
// a network management system ("client") can subscribe to state values,
// Interface. This interface is defined to be a standard interface that
// a network management system ("client") can use to subscribe to state values,
// retrieve snapshots of state information, and manipulate the state of a data
// tree supported by a device ("target").
//
Expand All @@ -47,7 +47,7 @@ option java_package = "com.github.gnmi.proto";

service gNMI {
// Capabilities allows the client to retrieve the set of capabilities that
// is supported by the target. This allows the target to validate the
// are supported by the target. This allows the client to validate the
// service version that is implemented and retrieve the set of models that
// the target supports. The models can then be specified in subsequent RPCs
// to restrict the set of data that is utilized.
Expand All @@ -60,19 +60,19 @@ service gNMI {
// Reference: gNMI Specification Section 3.3
rpc Get(GetRequest) returns (GetResponse);
// Set allows the client to modify the state of data on the target. The
// paths to modified along with the new values that the client wishes
// to set the value to.
// paths to be modified along with the new values that the client wishes
// to set the values to.
// Reference: gNMI Specification Section 3.4
rpc Set(SetRequest) returns (SetResponse);
// Subscribe allows a client to request the target to send it values
// Subscribe allows a client to request the target to send the client values
// of particular paths within the data tree. These values may be streamed
// at a particular cadence (STREAM), sent one off on a long-lived channel
// (POLL), or sent as a one-off retrieval (ONCE).
// Reference: gNMI Specification Section 3.5
rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeResponse);
}

// Notification is a re-usable message that is used to encode data from the
// Notification is a reusable message that is used to encode data from the
// target to the client. A Notification carries two types of changes to the data
// tree:
// - Deleted values (delete) - a set of paths that have been removed from the
Expand All @@ -81,7 +81,7 @@ service gNMI {
// whose value has changed in the data tree.
// Reference: gNMI Specification Section 2.1
message Notification {
int64 timestamp = 1; // Timestamp in nanoseconds since Epoch.
int64 timestamp = 1; // Timestamp in nanoseconds since UnixEpoch.
Path prefix = 2; // Prefix used for paths in the message.
repeated Update update = 4; // Data elements that have changed values.
repeated Path delete = 5; // Data elements that have been deleted.
Expand All @@ -93,8 +93,8 @@ message Notification {
reserved 3;
}

// Update is a re-usable message that is used to store a particular Path,
// Value pair.
// Update is a reusable message that is used to store a particular Path / Value
// pair.
// Reference: gNMI Specification Section 2.1
message Update {
Path path = 1; // The path (key) for the update.
Expand Down Expand Up @@ -142,7 +142,7 @@ message Path {
// Elements of the path are no longer encoded as a string, but rather within
// the elem field as a PathElem message.
repeated string element = 1 [deprecated = true];
string origin = 2; // Label to disambiguate path.
string origin = 2; // Label to disambiguate paths.
repeated PathElem elem = 3; // Elements of the path.
string target = 4; // The name of the target
// (Sec. 2.2.2.1)
Expand Down Expand Up @@ -206,8 +206,7 @@ message Decimal64 {
// ScalarArray is used to encode a mixed-type array of values.
message ScalarArray {
// The set of elements within the array. Each TypedValue message should
// specify only elements that have a field identifier of 1-7 (i.e., the
// values are scalar values).
// specify only elements that are not deprecated scalar values.
repeated TypedValue element = 1;
}

Expand Down Expand Up @@ -299,7 +298,7 @@ message SubscriptionList {
message Subscription {
Path path = 1; // The data tree path.
SubscriptionMode mode = 2; // Subscription mode to be used.
uint64 sample_interval = 3; // ns between samples in SAMPLE mode.
uint64 sample_interval = 3; // nanoseconds between samples in SAMPLE mode.
// Indicates whether values that have not changed should be sent in a SAMPLE
// subscription.
bool suppress_redundant = 4;
Expand Down Expand Up @@ -337,11 +336,11 @@ message SetRequest {
repeated Path delete = 2; // Paths to be deleted from the data tree.
repeated Update replace = 3; // Updates specifying elements to be replaced.
repeated Update update = 4; // Updates specifying elements to updated.
// Updates specifying elements to union and then replace the data tree.
// Updates specifying elements to union and then replace the data tree.
// See the gNMI specification at
// https:/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md
// for details.
repeated Update union_replace = 6;
repeated Update union_replace = 6;
// Extension messages associated with the SetRequest. See the
// gNMI extension specification for further definition.
repeated gnmi_ext.Extension extension = 5;
Expand All @@ -351,17 +350,16 @@ message SetRequest {
// client. It reports the result of the modifications to the data tree that were
// specified by the client. Errors for this RPC should be reported using the
// https:/googleapis/googleapis/blob/master/google/rpc/status.proto
// message in the RPC return. The gnmi.Error message can be used to add
// additional details where required. Reference: gNMI Specification
// Section 3.4.2
// message in the RPC return.
// Reference: gNMI Specification Section 3.4.2
message SetResponse {
Path prefix = 1; // Prefix used for paths.
// A set of responses specifying the result of the operations specified in
// the SetRequest.
repeated UpdateResult response = 2;
Error message = 3
[deprecated = true]; // The overall status of the transaction.
int64 timestamp = 4; // Timestamp of transaction (ns since epoch).
int64 timestamp = 4; // Timestamp of transaction (nanoseconds since epoch).
// Extension messages associated with the SetResponse. See the
// gNMI extension specification for further definition.
repeated gnmi_ext.Extension extension = 5;
Expand Down Expand Up @@ -391,7 +389,7 @@ message UpdateResult {

// GetRequest is sent when a client initiates a Get RPC. It is used to specify
// the set of data elements for which the target should return a snapshot of
// data. The use_models field specifies the set of schema modules that are to
// data. The use_models field specifies the set of schema models that are to
// be used by the target - where use_models is not specified then the target
// must use all schema models that it has.
// Reference: gNMI Specification Section 3.3.1
Expand Down Expand Up @@ -449,8 +447,8 @@ message CapabilityResponse {
repeated gnmi_ext.Extension extension = 4;
}

// ModelData is used to describe a set of schema modules. It can be used in a
// CapabilityResponse where a target reports the set of modules that it
// ModelData is used to describe a set of schema models. It can be used in a
// CapabilityResponse where a target reports the set of models that it
// supports, and within the SubscribeRequest and GetRequest messages to specify
// the set of models from which data tree elements should be reported.
// Reference: gNMI Specification Section 3.2.3
Expand Down