Write some crappy docs on annotations, and some other tweaks.

c++/src/capnproto/benchmark/carsales.capnp

@@ -21,6 +21,9 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+using Cxx = import "/capnproto/c++.capnp";
+$Cxx.namespace("capnproto::benchmark::capnp");
+
 struct ParkingLot {
   cars@0: List(Car);
 }

c++/src/capnproto/benchmark/catrank.capnp

@@ -21,6 +21,9 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+using Cxx = import "/capnproto/c++.capnp";
+$Cxx.namespace("capnproto::benchmark::capnp");
+
 struct SearchResultList {
   results@0: List(SearchResult);
 }

c++/src/capnproto/benchmark/eval.capnp

@@ -21,6 +21,9 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+using Cxx = import "/capnproto/c++.capnp";
+$Cxx.namespace("capnproto::benchmark::capnp");
+
 enum Operation {
   add @0;
   subtract @1;

c++/src/capnproto/c++.capnp

@@ -24,4 +24,4 @@
 $id("v3JF2GP4Supe9JSSJ3pnSdUqhJI");
 $namespace("capnproto::annotations");
 
-annotation namespace: Text on(file);
+annotation namespace(file): Text;

c++/src/capnproto/capnpc.ekam-rule

@@ -49,4 +49,4 @@ fi
 
 # When exception stack traces are needed, add: +RTS -xc -RTS
 LD_PRELOAD=$INTERCEPTOR DYLD_FORCE_FLAT_NAMESPACE= DYLD_INSERT_LIBRARIES=$INTERCEPTOR \
-$CAPNPC -oc++ "$INPUT" 3>&1 4<&0 >&2
+$CAPNPC -I. -oc++ "$INPUT" 3>&1 4<&0 >&2

compiler/src/Parser.hs

@@ -295,11 +295,10 @@ paramDecl = do
 annotationDecl = do
     annotationKeyword
     name <- located varIdentifier
-    colon
-    t <- typeExpression
-    onKeyword
     targets <- try (parenthesized asterisk >> return allAnnotationTargets)
            <|> parenthesizedList annotationTarget
+    colon
+    t <- typeExpression
     annotations <- many annotation
     return (AnnotationDecl name t annotations targets)
 allAnnotationTargets = [minBound::AnnotationTarget .. maxBound::AnnotationTarget]

doc/_plugins/capnp_lexer.py

@@ -14,14 +14,14 @@ class CapnpLexer(RegexLexer):
             (r'@[0-9]*', Name.Decorator),
             (r'=', Literal, 'expression'),
             (r':', Name.Class, 'type'),
-            (r'@[0-9]*', Token.Annotation),
-            (r'(struct|enum|interface|union|import|using|const|option|in|of|on|as|with|from)\b',
+            (r'\$', Name.Attribute, 'annotation'),
+            (r'(struct|enum|interface|union|import|using|const|annotation|in|of|on|as|with|from)\b',
                 Token.Keyword),
             (r'[a-zA-Z0-9_.]+', Token.Name),
-            (r'[^#@=:a-zA-Z0-9_]+', Text),
+            (r'[^#@=:$a-zA-Z0-9_]+', Text),
         ],
         'type': [
-            (r'[^][=;,()]+', Name.Class),
+            (r'[^][=;,(){}$]+', Name.Class),
             (r'[[(]', Name.Class, 'parentype'),
             (r'', Name.Class, '#pop')
         ],
@@ -32,7 +32,7 @@ class CapnpLexer(RegexLexer):
             (r'', Name.Class, '#pop')
         ],
         'expression': [
-            (r'[^][;,()]+', Literal),
+            (r'[^][;,(){}$]+', Literal),
             (r'[[(]', Literal, 'parenexp'),
             (r'', Literal, '#pop')
         ],
@@ -42,6 +42,17 @@ class CapnpLexer(RegexLexer):
             (r'[])]', Literal, '#pop'),
             (r'', Literal, '#pop')
         ],
+        'annotation': [
+            (r'[^][;,(){}=:]+', Name.Attribute),
+            (r'[[(]', Name.Attribute, 'annexp'),
+            (r'', Name.Attribute, '#pop')
+        ],
+        'annexp': [
+            (r'[^][;()]+', Name.Attribute),
+            (r'[[(]', Name.Attribute, '#push'),
+            (r'[])]', Name.Attribute, '#pop'),
+            (r'', Name.Attribute, '#pop')
+        ],
     }
 
 if __name__ == "__main__":

doc/cxx.md

@@ -338,6 +338,25 @@ details.
 
 There is an [example](#example_usage) of all this at the beginning of this page.
 
+## Setting a Namespace
+
+You probably want your generated types to live in a C++ namespace.  You will need to import
+`/capnproto/c++.capnp` and use the `namespace` annotation it defines:
+
+{% highlight capnp %}
+Cxx = import "/capnproto/c++.capnp";
+$Cxx.namespace("foo::bar::baz");
+{% endhighlight %}
+
+Note that for this to work, `capnproto/c++.capnp` must be located in the search path specified with
+`-I` options.  This file is found in the Cap'n Proto source repo, so you could invoke `capnpc` like
+so:
+
+    capnpc -I$CAPNPROTO_GIT_ROOT/c++/src -oc++ myproto.capnp
+
+As of this writing, the file is not automatically installed anywhere, but in the future it will
+be.
+
 ## Reference
 
 The runtime library contains lots of useful features not described on this page.  For now, the

doc/language.md

@@ -294,6 +294,75 @@ struct Foo {
 }
 {% endhighlight %}
 
+The above imports specify relative paths.  If the path begins with a `/`, it is absolute -- in
+this case, `capnpc` searches for the file in each of the search path directories specified with
+`-I`.
+
+### Annotations
+
+Sometimes you want to attach extra information to parts of your protocol that isn't part of the
+Cap'n Proto language.  This information might control details of a particular code generator, or
+you might even read it at run time to assist in some kind of dynamic message processing.  For
+example, you might create a field annotation which means "hide from the public", and when you send
+a message to an external user, you might invoke some code first that iterates over your message and
+removes all of these hidden fields.
+
+You may declare annotations and use them like so:
+
+{% highlight capnp %}
+# Declare an annotation 'foo' which applies to struct and enum types.
+annotation foo(struct, enum) :Text;
+
+# Apply 'foo' to to MyType.
+struct MyType $foo("bar") {
+  # ...
+}
+{% endhighlight %}
+
+The possible targets for an annotation are: `file`, `struct`, `field`, `union`, `enum`, `enumerant`,
+`interface`, `method`, `parameter`, `annotation`, `const`.  You may also specify `*` to cover them
+all.
+
+{% highlight capnp %}
+# 'baz' can annotate anything!
+annotation baz(*) :Int32;
+
+$baz(1);  # Annotate the file.
+
+struct MyStruct $baz(2) {
+  myField @0 :Text = "default" $baz(3);
+  myUnion @1 union $baz(4) {
+    # ...
+  }
+}
+
+enum MyEnum $baz(5) {
+  myEnumerant @0 $baz(6);
+}
+
+interface MyInterface $baz(7) {
+  myMethod(myParam :Text $baz(9)) :Void $baz(8);
+}
+
+annotation myAnnotation(struct) :Int32 $baz(10);
+const myConst :Int32 = 123 $baz(11);
+{% endhighlight %}
+
+`Void` annotations can omit the value.  Struct-typed annotations are also allowed.
+
+{% highlight capnp %}
+annotation qux(struct, field) :Void;
+
+struct MyStruct $qux {
+  string $0 :Text $qux;
+  number $1 :Int32 $qux;
+}
+
+annotation corge(file) :MyStruct;
+
+$corge(string = "hello", number = 123);
+{% endhighlight %}
+
 ## Evolving Your Protocol
 
 A protocol can be changed in the following ways without breaking backwards-compatibility:

doc/stylesheets/pygment_trac.css

@@ -72,3 +72,4 @@
 .highlight .capnp .nd { color: #0099FF; font-weight: normal; } /* @N */
 .highlight .capnp .l { color: #003399; } /* = value */
 .highlight .capnp .nc { color: #009900; font-weight: normal; } /* :Type */
+.highlight .capnp .na { color: #999900; font-weight: normal; } /* $x */