Permalink
Browse files

Docs: Added more info to ext/descriptor README, see #757

  • Loading branch information...
dcodeIO committed Apr 13, 2017
1 parent 1fc911c commit 6493f52013c92a34b8305a25068ec7b8c4c29d54
Showing with 43 additions and 5 deletions.
  1. +43 −5 ext/descriptor/README.md
@@ -1,7 +1,7 @@
protobufjs/ext/descriptor
=========================
Experimental [protobuf.js](https://github.com/dcodeIO/protobuf.js) extension for interoperability with descriptor.proto types.
Experimental extension for interoperability with descriptor.proto types.
Usage
-----
@@ -10,12 +10,50 @@ Usage
var protobuf = require("protobufjs"),
descriptor = require("protobufjs/ext/descriptor");
var descriptor = ...; // either a FieldDescriptorSet buffer, a FieldDescriptorSet message instance or a corresponding valid JSON object
var root = protobuf.Root.fromDescriptor(descriptor);
var rootDescriptor = root.toDescriptor("proto3");
// take any extisting root object
var root = ...;
// convert it to the corresponding descriptor type
var fileDescriptorSet = root.toDescriptor("proto2");
// encode it
var buffer = descriptor.FileDescriptorSet.encode(fileDescriptorSet).finish();
// decode it back
var decoded = descriptor.FileDescriptorSet.decode(buffer);
// convert it back to a protobuf.js root
root = protobuf.Root.fromDescriptor(decoded, "proto2");
// and start all over again
```
API
---
The extension adds `.fromDescriptor(descriptor[, syntax])` and `#toDescriptor([syntax])` methods to reflection objects and exports the `.google.protobuf` namespace of the internally used `Root` instance containing the types present in descriptor.proto.
The extension adds `.fromDescriptor(descriptor[, syntax])` and `#toDescriptor([syntax])` methods to reflection objects and exports the `.google.protobuf` namespace of the internally used `Root` instance containing the following types present in descriptor.proto.
| Descriptor type | protobuf.js type | Remarks
|--------------------------|------------------|---------
| FileDescriptorSet | Root |
| FileDescriptorProto | Root | not supported: dependencies, sourceCodeInfo
| FileOptions | Root | not supported
| DescriptorProto | Type |
| MessageOptions | Type | not supported
| FieldDescriptorProto | Field | not supported: defaultValue, jsonValue
| FieldOptions | Field | only packed
| OneofDescriptorProto | OneOf |
| OneofOptions | OneOf | not supported
| EnumDescriptorProto | Enum |
| EnumValueDescriptorProto | Enum |
| EnumOptions | Enum | only allowAlias
| EnumValueOptions | Enum | not supported
| ServiceDescriptorProto | Service |
| ServiceOptions | Service | not supported
| MethodDescriptorProto | Method |
| MethodOptions | Method | not supported
| UninterpretedOption | | not supported
| SourceCodeInfo | | not supported
| GeneratedCodeInfo | | not supported
Additionally, not all features of descriptor.proto translate perfectly to a protobuf.js root instance. A root instance has only limited knowlege of packages or individual files for example, which is then compensated by guessing.

0 comments on commit 6493f52

Please sign in to comment.