fix(mo-doc): include public variables in generated docs (#4626)

* Add 'value_sort' to extracted Value doc * Include public class variables in generated docs * Reformat
dfinity · Jul 25, 2024 · 4796965 · 4796965
1 parent 132b4b4
commit 4796965
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 9 deletions.
diff --git a/src/docs/adoc.ml b/src/docs/adoc.ml
@@ -121,7 +121,8 @@ let rec adoc_of_declaration :
   | Value value_doc ->
       header value_doc.name;
       signature (fun _ ->
-          bprintf buf "let %s" value_doc.name;
+          let sort = match value_doc.sort with Let -> "let" | Var -> "var" in
+          bprintf buf "%s %s" sort value_doc.name;
           opt_typ buf env value_doc.typ);
       doc_comment ()
   | Type type_doc ->

diff --git a/src/docs/extract.ml b/src/docs/extract.ml
@@ -28,7 +28,8 @@ and function_arg_doc = {
   doc : string option;
 }
 
-and value_doc = { name : string; typ : Syntax.typ option }
+and value_sort = Let | Var
+and value_doc = { sort : value_sort; name : string; typ : Syntax.typ option }
 
 and type_doc = {
   name : string;
@@ -117,14 +118,15 @@ struct
     | { it = Syntax.TupP args; _ } -> List.filter_map extract_args args
     | _ -> []
 
-  let extract_let_doc : Syntax.exp -> string -> declaration_doc =
-   fun exp name ->
+  let extract_value_doc : value_sort -> Syntax.exp -> string -> declaration_doc
+      =
+   fun sort exp name ->
     match exp.it with
     | Syntax.FuncE (_, _, type_args, args, typ, _, _) ->
         let args_doc = extract_func_args args in
         Function { name; typ; type_args; args = args_doc }
-    | Syntax.AnnotE (e, ty) -> Value { name; typ = Some ty }
-    | _ -> Value { name; typ = None }
+    | Syntax.AnnotE (e, ty) -> Value { sort; name; typ = Some ty }
+    | _ -> Value { sort; name; typ = None }
 
   let extract_obj_field_doc :
       Syntax.typ_field -> Syntax.typ_field * string option =
@@ -149,7 +151,23 @@ struct
                       List.filter_map (extract_dec_field mk_field_xref) fields;
                     sort;
                   } )
-        | _ -> Some (mk_xref (Xref.XValue name), extract_let_doc rhs name))
+        | _ -> Some (mk_xref (Xref.XValue name), extract_value_doc Let rhs name)
+        )
+    | Source.{ it = Syntax.VarD ({ it = name; _ }, rhs); _ } -> (
+        match rhs with
+        | Source.{ it = Syntax.ObjBlockE (sort, _, fields); _ } ->
+            let mk_field_xref xref = mk_xref (Xref.XClass (name, xref)) in
+            Some
+              ( mk_xref (Xref.XType name),
+                Object
+                  {
+                    name;
+                    fields =
+                      List.filter_map (extract_dec_field mk_field_xref) fields;
+                    sort;
+                  } )
+        | _ -> Some (mk_xref (Xref.XValue name), extract_value_doc Var rhs name)
+        )
     | Source.{ it = Syntax.TypD (name, ty_args, typ); _ } ->
         let doc_typ =
           match typ.it with

diff --git a/src/docs/html.ml b/src/docs/html.ml
@@ -275,7 +275,9 @@ let rec html_of_declaration : env -> Xref.t -> Extract.declaration_doc -> t =
   | Value value_doc ->
       h4 ~cls:"value-declaration" ~id
         (code
-           (keyword "public let "
+           (keyword "public "
+           ++ keyword
+                (match value_doc.sort with Let -> "let " | Var -> "var ")
            ++ fn_name value_doc.name
            ++ string " : "
            ++ Option.fold ~none:empty ~some:(html_of_type env) value_doc.typ))

diff --git a/src/docs/plain.ml b/src/docs/plain.ml
@@ -237,7 +237,8 @@ let rec declaration_header :
   | Value value_doc ->
       title buf lvl (Printf.sprintf "Value `%s`" value_doc.name);
       begin_block buf;
-      bprintf buf "let %s" value_doc.name;
+      let sort = match value_doc.sort with Let -> "let" | Var -> "var" in
+      bprintf buf "%s %s" sort value_doc.name;
       opt_typ buf value_doc.typ;
       end_block buf;
       doc_comment ()