Document IDs and 'Object' type.

doc/_plugins/capnp_lexer.py

@@ -11,7 +11,7 @@ class CapnpLexer(RegexLexer):
     tokens = {
         'root': [
             (r'#.*?$', Comment.Single),
-            (r'@[0-9]*', Name.Decorator),
+            (r'@[0-9a-zA-Z]*', Name.Decorator),
             (r'=', Literal, 'expression'),
             (r':', Name.Class, 'type'),
             (r'\$', Name.Attribute, 'annotation'),

doc/language.md

@@ -11,7 +11,10 @@ that message type in your desired language.
 
 For example:
 
-{% highlight capnp %}
+{% highlight python %}
+# unique file ID, generated by capnpc -i
+@0xdbb9ad1f14bf0b36;
+
 struct Person {
   name @0 :Text;
   birthdate @3 :Date;
@@ -363,8 +366,54 @@ annotation corge(file) :MyStruct;
 $corge(string = "hello", number = 123);
 {% endhighlight %}
 
+### Unique IDs
+
+A Cap'n Proto file must have a unique 64-bit ID, and each type and annotation defined therein may
+also have an ID.  Use `capnpc -i` to generate a new ID randomly.  ID specifications begin with `@`:
+
+{% highlight capnp %}
+# file ID
+@0xdbb9ad1f14bf0b36;
+
+struct Foo @0x8db435604d0d3723 {
+  # ...
+}
+
+enum Bar @0xb400f69b5334aab3 {
+  # ...
+}
+
+interface Baz @0xf7141baba3c12691 {
+  # ...
+}
+
+annotation qux @0xf8a1bedf44c89f00 (field) :Text;
+{% endhighlight %}
+
+If you omit the ID for a type or annotation, one will be assigned automatically.  This default
+ID is derived from the declaration's name combined with the ID of the parent scope (i.e. the file
+ID for top-level declarations or the outer type's ID for nested declarations).  In general, you
+would only specify an explicit ID for a declaration if that declaration has been renamed or moved
+and you want the ID to stay the same for backwards-compatibility.
+
+IDs exist to provide a relatively short yet unambiguous way to refer to a type or annotation from
+another context.  They may be used for representing schemas, for tagging dynamically-typed fields,
+etc.  Most languages prefer instead to define a symbolic global namespace e.g. full of "packages",
+but this would have some important disadvantages in the context of Cap'n Proto:
+
+* Programmers often feel the need to change symbolic names and organization in order to make their
+  code cleaner.
+* It's easy for symbolic names to collide, and these collisions could be hard to detect in a large
+  distributed system with many different binaries using different versions of protocols.
+* Fully-qualified type names may be large and waste space when transmitted on the wire.
+
 ## Advanced Topics
 
+### Dynamically-typed Fields
+
+A struct may have a field with type `Object`.  This field's value can be of any pointer type -- i.e.
+any struct, interface, list, or blob.  This is essentially like a `void*` in C.
+
 ### Inlining Structs
 
 Say you have a small struct which you know will never add new fields.  For efficiency, you may want