Added comments to parsetree.mli

(Patch by Yotam Barnoy)

Specifically, I documented some more obscure features that weren't
obvious from reading the existing comments.

Discussion of these comments can be found on the mailing list at
  https://sympa.inria.fr/sympa/arc/caml-list/2014-04/msg00022.html

git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@14577 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02

parsing/parsetree.mli

@@ -17,14 +17,19 @@ open Asttypes
 (** {2 Extension points} *)
 
 type attribute = string loc * payload
-      (* [@id ARG]
-         [@@id ARG]
+       (* [@id ARG]
+          [@@id ARG]
+
+          Metadata containers passed around within the AST.
+          The compiler ignores unknown attributes.
        *)
 
 and extension = string loc * payload
       (* [%id ARG]
          [%%id ARG]
-       *)
+
+         Sub-language placeholder -- rejected by the typechecker.
+      *)
 
 and attributes = attribute list
 
@@ -115,7 +120,12 @@ and row_field =
            [`A of T]              ( false, [T] )
            [`A of T1 & .. & Tn]   ( false, [T1;...Tn] )
            [`A of & T1 & .. & Tn] ( true,  [T1;...Tn] )
-         *)
+
+          - The 2nd field is true if the tag contains a
+            constant (empty) constructor.
+          - '&' occurs when several types are used for the same constructor
+            (see 4.2 in the manual)
+        *)
   | Rinherit of core_type
         (* [ T ] *)
 
@@ -682,7 +692,11 @@ and structure_item_desc =
   | Pstr_modtype of module_type_declaration
         (* module type S = MT *)
   | Pstr_open of override_flag * Longident.t loc * attributes
-        (* open X *)
+        (* open! X - true
+           open  X - false
+
+           override_flag silences the 'used identifier shadowing' warning
+           *)
   | Pstr_class of class_declaration list
         (* class c1 = ... and ... and cn = ... *)
   | Pstr_class_type of class_type_declaration list
@@ -719,6 +733,7 @@ and module_binding =
 type toplevel_phrase =
   | Ptop_def of structure
   | Ptop_dir of string * directive_argument
+     (* #use, #load ... *)
 
 and directive_argument =
   | Pdir_none