More docs about mojom.

docs/intro/mojom_idl.md

Index: docs/intro/mojom_idl.md
diff --git a/docs/intro/mojom_idl.md b/docs/intro/mojom_idl.md
index e739dbaf7d6beea6439d8cb1cdc6c15952c48c9d..627846a04f0b96fce4d124450ef8145773eae3a1 100644
--- a/docs/intro/mojom_idl.md
+++ b/docs/intro/mojom_idl.md
@@ -21,7 +21,7 @@ with one endpoint designated the *client* (which sends *request* messages and
 receives *response* messages) and the other designed that *server* or *impl*
 (which receives request messages and sends response messages).
 
-For example, take the following Mojom interface definition:
+For example, take the following Mojom interface declaration:
 ```mojom
 interface MyInterface {
   Foo(int32 a, string b);
@@ -54,10 +54,26 @@ containing no data. Note that even though the response has no data, a response
 message must nonetheless be sent, functioning as an "ack". (Thus this is
 different from not having a response, as was the case for `Foo`.)
 
+## Structs
+
+Mojom defines a way of serializing data structures (with the Mojom IDL providing
+a way of specifying those data structures). A Mojom *struct* is the basic unit
+of serialization. As we saw above, messages are just basically just structs,

[vardhan, 2016/03/03 22:09:32]

are basically just

+with a small amount of additional metadata.
+
+Here is a simple example of a struct declaration:
+```mojom
+struct MyStruct {
+  int32 a;
+  string b;
+};
+```
+We will discuss in greater detail how structs are declared later.
+
 ### Names in Mojom
 
-Names in Mojom are not important. Except in affecting compatibility at level of
-source code (when generating bindings), names in a Mojom file may be changed
+Names in Mojom are not important. Except in affecting compatibility at the level
+of source code (when generating bindings), names in a Mojom file may be changed
 arbitrarily without any effect on the "meaning" of the Mojom file (subject to
 basic language requirements, e.g., avoiding collisions with keywords and other
 names). E.g., the following is completely equivalent to the interface discussed
@@ -99,38 +115,138 @@ discuss this matter further here.
 **TODO(vtl)**: Maybe mention exceptions to this in attributes (e.g.,
 `ServiceName`).
 
+## Mojom files
 
-**TODO(vtl)**: Write/(re)organize the sections below.
+A Mojom file consists of, in order:
+* an optional *module* declaration;
+* zero or more *import* statements (the order of these is not important); and
+* zero or more declarations of *struct*s, *interface*s, *union*s, *enum*s, or
+  *const*s (the order of these is not important).
+(These are all described further below.)
 
-## Structs
+Additionally, C/C++-style comments are supported (i.e., single-line comments
+starting with `//` or multi-line comments of the form `/* ... */`).
+
+As stated above, the order of struct/interface/union/enum/const declarations is
+not important. This is required to allow "cyclic" structures to be defined.
+Nonetheless, whenever possible, one should declare things before they are
+"used". For example, the following is valid but not recommended:
+```mojom
+// NOT recommended.
+
+const MyEnum kMyConst = kMyOtherConst;
+const MyEnum kMyOtherConst = A_VALUE;
+
+enum MyEnum {
+  A_VALUE,
+  ANOTHER_VALUE,
+};
+```
+
+### Naming style
+
+There is a standard style for naming things:
+* `StudlyCaps` (a.k.a. `CapitalizedCamelCase`) for: (struct, interface, union,
+  and enum) type names and message (a.k.a. function or method) names;
+* `unix_hacker_style` for field names (in structs and unions) and "parameter"
+  names;
+* `ALL_CAPS_UNIX_HACKER_STYLE` for enum value names; and
+* `kStudlyCaps` for const names.
+
+Following this style is highly recommended, since code generators for various
+languages will expect this style, in order to transform the names into a more
+language-appropriate style.
+
+### Module statement
+
+**TODO(vtl)**
 
-## Modules
+### Import declarations
+
+**TODO(vtl)**
+
+### Struct declarations
+
+A Mojom struct declaration consists of a finite sequence of *field declaration*,
+each of which consists of a *type*, a *name*, and optionally a *default value*
+(if applicable for the given type). (If no default value is declared, then the
+default is the default value for the field type, typically 0, null, or similar.)
+
+Additionally, a struct may contain enum and const declarations (**TODO(vtl)**:
+why not struct/union/interface declarations?). While the order of the field
+declarations (with respect to one another) is important, the ordering of the
+enum/const declarations (with respect to both the field declarations and other
+enum/const declarations) is not. (But as before, we recommend declaring things
+before "use".)
+
+Here is an example with these elements:
+```mojom
+struct Foo {
+  const int8 kSomeConstant = 123;
+
+  enum MyEnum {
+    A_VALUE,
+    ANOTHER_VALUE
+  };
+
+  int8 first_field = kSomeConstant;
+  uint32 second_field = 123;
+  MyEnum etc_etc = A_VALUE;
+  float a;    // Default value is 0.
+  string? b;  // Default value is null.
+};
+```
+(Note that `kSomeConstant` may be referred to as `Foo.kSomeConstant` and,
+similarly, `MyEnum` as `Foo.MyEnum`. This is required outside of the `Foo`
+declaration.)
+
+### Interface declarations
+
+**TODO(vtl)**
+
+### Union declarations
+
+**TODO(vtl)**
+
+### Enum declarations
+
+**TODO(vtl)**
+
+### Const declarations
+
+**TODO(vtl)**
+
+**TODO(vtl)**: Write/(re)organize the sections below.
 
 ## Data types
 
 ### Primitive types
 
-### Enums
+#### Standard types
+
+#### Enum types
+
+### "Pointer" types
 
-### Strings
+#### Nullability
 
-### Nullability
+#### Strings
 
-### Structs
+#### Maps
 
-### Arrays
+#### Structs
 
-### Maps
+#### Arrays
 
-### Unions
+#### Unions
 
-### Handle values
+### Handle types
 
-### Interface values
+#### Raw handle types
 
-### Interface requests
+#### Interface types
 
-## Consts
+#### Interface request types
 
 ## Annotations