diff --git a/idl/pEpACIDLang.yml2 b/idl/pEpACIDLang.yml2
index 6708bab..745b28f 100644
--- a/idl/pEpACIDLang.yml2
+++ b/idl/pEpACIDLang.yml2
@@ -59,27 +59,43 @@ idl {
     }
 }
 
-
+// Basic
+// -----
 decl package @name;
 decl api @name;
 
-// deftype
+
+// Deftype
+// -------
 decl deftype @name;
 decl as @type;
 
-// enum
+
+// Enum
+// ----
 decl enum @name;
 decl item @name;
+// optional attrib 'doc'
 
-// struct
+
+// Struct
+// ------
 decl struct @name;
-decl field @type @name;  // optional: function=free for a free function
+decl field @optional @type @name;
+// optional attrib 'doc'
+// optional attrib 'deallocator' (for non-idl types)
 
-// method
+// Method
+// ------
 decl method @name;
+//optional attrib 'brief'
+//optional attrib 'note'
+
 decl param @mode @type @name;
-decl throws @name;
+//optional attrib 'doc'
 
+decl throws @name;
+//optional attrib 'doc'