diff --git a/src/ast.ml b/src/ast.ml
index 5d21ecd2..3db32f82 100644
--- a/src/ast.ml
+++ b/src/ast.ml
@@ -28,6 +28,10 @@ module MakeBlock(I : T) = struct
       defs: 'attr I.t list;
     }
 
+  (* The 'attr parameter is present in all variants in this type. We use it to associate
+     extra information to each node in the AST. In the common case, the attributes type defined
+     above is used. We might eventually have an alternative function parse blocks while keeping
+     concrete information such as source location and we'll use it for that as well. *)
   type 'attr block =
     | Paragraph of 'attr * 'attr I.t
     | List of 'attr * list_type * list_spacing * 'attr block list list
@@ -46,6 +50,7 @@ type 'attr link =
     title: string option;
   }
 
+(* See comment on the block type about the 'attr parameter *)
 and 'attr inline =
   | Concat of 'attr * 'attr inline list
   | Text of 'attr * string