| Zack Williams | e940c7a | 2019-08-21 14:25:39 -0700 | [diff] [blame] | 1 | // Package desc contains "rich descriptors" for protocol buffers. The built-in |
| 2 | // descriptor types are simple protobuf messages, each one representing a |
| 3 | // different kind of element in the AST of a .proto source file. |
| 4 | // |
| 5 | // Because of this inherent "tree" quality, these build-in descriptors cannot |
| 6 | // refer to their enclosing file descriptor. Nor can a field descriptor refer to |
| 7 | // a message or enum descriptor that represents the field's type (for enum and |
| 8 | // nested message fields). All such links must instead be stringly typed. This |
| 9 | // limitation makes them much harder to use for doing interesting things with |
| 10 | // reflection. |
| 11 | // |
| 12 | // Without this package, resolving references to types is particularly complex. |
| 13 | // For example, resolving a field's type, the message type an extension extends, |
| 14 | // or the request and response types of an RPC method all require searching |
| 15 | // through symbols defined not only in the file in which these elements are |
| 16 | // declared but also in its transitive closure of dependencies. |
| 17 | // |
| 18 | // "Rich descriptors" avoid the need to deal with the complexities described |
| 19 | // above. A rich descriptor has all type references resolved and provides |
| 20 | // methods to access other rich descriptors for all referenced elements. Each |
| 21 | // rich descriptor has a usefully broad API, but does not try to mimic the full |
| 22 | // interface of the underlying descriptor proto. Instead, every rich descriptor |
| 23 | // provides access to that underlying proto, for extracting descriptor |
| 24 | // properties that are not immediately accessible through rich descriptor's |
| 25 | // methods. |
| 26 | // |
| 27 | // Rich descriptors can be accessed in similar ways as their "poor" cousins |
| 28 | // (descriptor protos). Instead of using proto.FileDescriptor, use |
| 29 | // desc.LoadFileDescriptor. Message descriptors and extension field descriptors |
| 30 | // can also be easily accessed using desc.LoadMessageDescriptor and |
| 31 | // desc.LoadFieldDescriptorForExtension, respectively. |
| 32 | // |
| 33 | // It is also possible create rich descriptors for proto messages that a given |
| 34 | // Go program doesn't even know about. For example, they could be loaded from a |
| 35 | // FileDescriptorSet file (which can be generated by protoc) or loaded from a |
| 36 | // server. This enables interesting things like dynamic clients: where a Go |
| 37 | // program can be an RPC client of a service it wasn't compiled to know about. |
| 38 | // |
| 39 | // Also see the grpcreflect, dynamic, and grpcdynamic packages in this same |
| 40 | // repo to see just how useful rich descriptors really are. |
| 41 | package desc |