add mo-doc 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

@@ -24,15 +24,15 @@ let write_file : string -> string -> unit =
   close_out oc
 
 let extract : bool -> string -> extracted option =
- fun skip_comments in_file ->
+ 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 skip_comments prog with
+      match extract_docs strip_comments prog with
       | Error err ->
           Printf.eprintf "Skipping %s:\n%s\n" in_file err;
           None
@@ -91,26 +91,26 @@ let make_render_inputs : string -> string -> bool -> (string * Common.render_inp
     all_files
 
 let start : output_format -> string -> string -> bool -> unit =
- fun output_format src out skip_comments ->
+ 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 skip_comments 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 skip_comments 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 skip_comments 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/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,21 +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 : bool -> Syntax.prog -> (extracted, string) result =
- fun skip_comments prog ->
+ fun strip_comments prog ->
  let lookup_trivia (line, column) =
-    if skip_comments then None else
     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
@@ -236,11 +241,14 @@ let extract_docs : bool -> 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;
         }