blob: 1740dce7d09f7954aef4355731d403669bb16b12 [file] [log] [blame]
Zack Williamse940c7a2019-08-21 14:25:39 -07001// 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.
41package desc