experiment: mo-doc add option to strip comments

doc/Makefile

@@ -16,6 +16,9 @@ overview-slides.html : overview-slides.md
 	  # # -V minScale=2 \
 	  # # -V maxScale=2
 
+outline:
+	mo-doc --strip-comments --source $(MOTOKO_BASE) --output $(OUT)/outline --format plain
+
 base:
 	mo-doc --source $(MOTOKO_BASE) --output $(OUT)/base --format plain
 

src/docs/docs.ml

@@ -23,16 +23,16 @@ let write_file : string -> string -> unit =
   flush oc;
   close_out oc
 
-let extract : string -> extracted option =
- fun in_file ->
+let extract : bool -> string -> extracted option =
+ fun strip_comments in_file ->
   let parse_result = Pipeline.parse_file Source.no_region in_file in
   match parse_result with
   | Error err ->
       Printf.eprintf "Skipping %s:\n" in_file;
       Diag.print_messages err;
       None
   | Ok ((prog, _), _) -> (
-      match extract_docs prog with
+      match extract_docs strip_comments prog with
       | Error err ->
           Printf.eprintf "Skipping %s:\n%s\n" in_file err;
           None
@@ -69,9 +69,9 @@ let list_files : string -> string -> (string * string * string) list =
       |> fun f -> (file, Filename.concat output f, f))
     all_files
 
-let make_render_inputs : string -> string -> (string * Common.render_input) list
+let make_render_inputs : string -> string -> bool -> (string * Common.render_input) list
     =
- fun source output ->
+ fun source output strip_comments ->
   let all_files = List.sort compare (list_files source output) in
   let all_modules = List.map (fun (_, _, rel) -> rel) all_files in
   List.filter_map
@@ -87,30 +87,30 @@ let make_render_inputs : string -> string -> (string * Common.render_input) list
                 module_comment;
                 declarations = docs;
               } ))
-        (extract input))
+        (extract strip_comments input))
     all_files
 
-let start : output_format -> string -> string -> unit =
- fun output_format src out ->
+let start : output_format -> string -> string -> bool -> unit =
+ fun output_format src out strip_comments ->
   (try Unix.mkdir out 0o777 with _ -> ());
   match output_format with
   | Plain ->
-      let inputs = make_render_inputs src out in
+      let inputs = make_render_inputs src out strip_comments in
       List.iter
         (fun (out, input) -> write_file (out ^ ".md") (Plain.render_docs input))
         inputs;
       write_file
         (Filename.concat out "index.md")
         (Plain.make_index (List.map snd inputs))
   | Adoc ->
-      let inputs = make_render_inputs src out in
+      let inputs = make_render_inputs src out strip_comments in
       List.iter
         (fun (out, input) ->
           write_file (out ^ ".adoc") (Adoc.render_docs input))
         inputs
   | Html ->
       write_file (Filename.concat out "styles.css") Styles.styles;
-      let inputs = make_render_inputs src out in
+      let inputs = make_render_inputs src out strip_comments in
       List.iter
         (fun (out, input) ->
           write_file (out ^ ".html") (Html.render_docs input))

src/docs/docs.mli

@@ -2,4 +2,4 @@ type output_format = Plain | Adoc | Html
 
 (** Generates documentation for all Motoko source files in the _input_ directory
  ** inside the _output_ directory using the specified _output format_. *)
-val start : output_format -> string -> string -> unit
+val start : output_format -> string -> string -> bool -> unit

src/docs/extract.ml

@@ -81,8 +81,14 @@ module MakeExtract (Env : sig
   val all_decs : Syntax.dec_field list
   val imports : (string * string) list
   val find_trivia : Source.region -> Trivia.trivia_info
+  val strip_comments : bool
 end) =
 struct
+
+  let doc_comment_of_trivia_info ti =
+    if Env.strip_comments then None else
+    Trivia.doc_comment_of_trivia_info ti
+
   let namespace : Namespace.t =
     let import_ns = Namespace.from_imports Env.imports in
     let module_ns = Namespace.from_module Env.all_decs in
@@ -97,15 +103,15 @@ struct
           {
             name;
             typ = None;
-            doc = Trivia.doc_comment_of_trivia_info (Env.find_trivia at);
+            doc = doc_comment_of_trivia_info (Env.find_trivia at);
           }
     | Source.{ it = Syntax.AnnotP (p, ty); at; _ } ->
         Option.map
           (fun x ->
             {
               x with
               typ = Some ty;
-              doc = Trivia.doc_comment_of_trivia_info (Env.find_trivia at);
+              doc = doc_comment_of_trivia_info (Env.find_trivia at);
             })
           (extract_args p)
     | Source.{ it = Syntax.WildP; _ } -> None
@@ -131,7 +137,7 @@ struct
   let extract_obj_field_doc :
       Syntax.typ_field -> Syntax.typ_field * string option =
    fun ({ at; _ } as tf) ->
-    (tf, Trivia.doc_comment_of_trivia_info (Env.find_trivia at))
+    (tf, doc_comment_of_trivia_info (Env.find_trivia at))
 
   let rec extract_doc mk_xref = function
     | Source.
@@ -211,20 +217,20 @@ struct
              {
                xref;
                doc_comment =
-                 Trivia.doc_comment_of_trivia_info
+                 doc_comment_of_trivia_info
                    (Env.find_trivia dec_field.at);
                declaration = decl_doc;
              })
     else None
 end
 
-let extract_docs : Syntax.prog -> (extracted, string) result =
- fun prog ->
-  let lookup_trivia (line, column) =
+let extract_docs : bool -> Syntax.prog -> (extracted, string) result =
+ fun strip_comments prog ->
+ let lookup_trivia (line, column) =
     PosTable.find_opt prog.note.Syntax.trivia Trivia.{ line; column }
   in
   let find_trivia (parser_pos : Source.region) : Trivia.trivia_info =
-    lookup_trivia Source.(parser_pos.left.line, parser_pos.left.column)
+     lookup_trivia Source.(parser_pos.left.line, parser_pos.left.column)
     |> Option.get
   in
   let module_docs = find_trivia prog.at in
@@ -235,11 +241,14 @@ let extract_docs : Syntax.prog -> (extracted, string) result =
         let all_decs = decls
         let imports = imports
         let find_trivia = find_trivia
+        let strip_comments = strip_comments
       end) in
       let docs = List.filter_map (Ex.extract_dec_field Fun.id) decls in
       Ok
         {
-          module_comment = Trivia.doc_comment_of_trivia_info module_docs;
+          module_comment =
+            if strip_comments then None else
+            Trivia.doc_comment_of_trivia_info module_docs;
           lookup_type = Ex.lookup_type;
           docs;
         }

src/exes/mo_doc.ml

@@ -1,6 +1,7 @@
 let source : string ref = ref "src"
 let output : string ref = ref "docs"
 let format : Docs.output_format ref = ref Docs.Html
+let strip_comments = ref false
 
 let set_source s = source := s
 let set_output o = output := o
@@ -21,6 +22,9 @@ let argspec = [
     ; "--format",
       Arg.String set_format,
       "<format>  specifies the generated format. One of `html`, `adoc`, or `plain` Defaults to `html`"
+    ; "--strip-comments",
+      Arg.Set strip_comments,
+      " ignore doc comments"
     ]
 
 let invalid s =
@@ -30,4 +34,4 @@ let invalid s =
 
 let () =
   Arg.parse argspec invalid usage;
-  Docs.start !format !source !output
+  Docs.start !format !source !output !strip_comments