add some code annotations

Author: lubegasimon

src/markdown/generator.ml

@@ -38,7 +38,8 @@ let rec source_code (s : Source.t) args =
       in
       match h with
       | Source.Elt i -> inline i args ++ continue t
-      | Tag (Some "arrow", _) -> text "->"
+      | Tag (Some "arrow", _) ->
+          text "->" (* takes care of the Entity branch of Inline.t *)
       | Tag (_, s) -> continue s ++ continue t)
 
 and inline (l : Inline.t) args =
@@ -173,10 +174,10 @@ let rec documented_src (l : DocumentedSrc.t) args nbsps =
             let doc = match doc with [] -> noop | doc -> block doc args in
             let content =
               match content with
-              | `D code ->
+              | `D code (* for record fields and polymorphic variants *) ->
                   paragraph
                     (item_prop ++ nbsps' ++ (nbsp ++ nbsp) ++ inline code args)
-              | `N l ->
+              | `N l (* for constructors *) ->
                   let c, rest = take_code l in
                   blocks
                     (paragraph