Skip to content

Commit 0ae51a1

Browse files
committed
doc: Update enum section in sdk guide
Signed-off-by: Luis Pabón <[email protected]>
1 parent 52c7c0b commit 0ae51a1

File tree

1 file changed

+19
-3
lines changed

1 file changed

+19
-3
lines changed

docs/dev-sdk.md

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,10 @@ Any changes to the protocol must bump the version by one. On the _master_ branch
4747
##### Enums
4848

4949
* Follow the [Google protobuf style for enums](https://developers.google.com/protocol-buffers/docs/style#enums)
50-
* Enum of zero value should be labeled as `XXX_UNKNOWN`, `XXX_NONE`, or `XXX_UNDEFINED` to check if it was not set.
51-
* Wrap enums in messages so that their string values are clearer. Example:
50+
* According to the Google guide, the enum of zero value should be labeled as `UNSPECIFIED` to check if it was not set since `0` is the default value set when the client does not provide it.
51+
* Wrap enums in messages so that their string values are clearer. Wrapping an enum in a message also has the benefit of not needing to prefix the enums with namespaced information. For example, instead of using the enum `XATTR_UNSPECIFIED`, the example above uses just `UNSPECIFIED` since it is inide the `Xattr` message. The generated code will be namepaced:
52+
53+
Proto:
5254

5355
```proto
5456
// Xattr defines implementation specific volume attribute
@@ -62,7 +64,16 @@ message Xattr {
6264
}
6365
```
6466

65-
Wrapping an enum in a message also has the benefit of not needing to prefix the enums with namespaced information. For example, instead of using the enum `XATTR_UNSPECIFIED`, the example above uses just `UNSPECIFIED` since it is inide the `Xattr` message. The generated code will be namepaced:
67+
Using the enum in a Proto
68+
69+
```proto
70+
message VolumeSpec {
71+
// Holds the extended attributes for the volume
72+
Xattr.Value xattr = 1;
73+
}
74+
```
75+
76+
Notice the namepaced and string values in the generated output code:
6677

6778
```go
6879
type Xattr_Value int32
@@ -82,6 +93,11 @@ var Xattr_Value_value = map[string]int32{
8293
"UNSPECIFIED": 0,
8394
"COW_ON_DEMAND": 1,
8495
}
96+
97+
typedef VolueSpec struct {
98+
// Holds the extended attributes for the volume
99+
Xattr Xattr_Value `protobuf:"varint,36,opt,name=xattr,enum=openstorage.api.Xattr_Value" json:"xattr,omitempty"`
100+
}
85101
```
86102

87103
##### Security

0 commit comments

Comments
 (0)