From 6493f52013c92a34b8305a25068ec7b8c4c29d54 Mon Sep 17 00:00:00 2001
From: dcodeIO <dcode@dcode.io>
Date: Thu, 13 Apr 2017 03:20:38 +0200
Subject: [PATCH] Docs: Added more info to ext/descriptor README, see #757

---
 ext/descriptor/README.md | 48 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/ext/descriptor/README.md b/ext/descriptor/README.md
index dff1bef32..36ffb136f 100644
--- a/ext/descriptor/README.md
+++ b/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.