From 98b9cf8d039466244d36204f297e1e280b2ce53d Mon Sep 17 00:00:00 2001 From: Claudio Russo Date: Fri, 6 Dec 2024 17:24:43 +0000 Subject: [PATCH 1/2] add --strip-comments flag to mo-doc --- src/docs/docs.ml | 22 +++++++++++----------- src/docs/docs.mli | 2 +- src/docs/extract.ml | 7 ++++--- src/exes/mo_doc.ml | 6 +++++- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/src/docs/docs.ml b/src/docs/docs.ml index 30c1d73bb30..b9262edcf3c 100644 --- a/src/docs/docs.ml +++ b/src/docs/docs.ml @@ -23,8 +23,8 @@ 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 skip_comments in_file -> let parse_result = Pipeline.parse_file Source.no_region in_file in match parse_result with | Error err -> @@ -32,7 +32,7 @@ let extract : string -> extracted option = Diag.print_messages err; None | Ok ((prog, _), _) -> ( - match extract_docs prog with + match extract_docs skip_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,15 +87,15 @@ 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 skip_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 skip_comments in List.iter (fun (out, input) -> write_file (out ^ ".md") (Plain.render_docs input)) inputs; @@ -103,14 +103,14 @@ let start : output_format -> string -> string -> unit = (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 skip_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 skip_comments in List.iter (fun (out, input) -> write_file (out ^ ".html") (Html.render_docs input)) diff --git a/src/docs/docs.mli b/src/docs/docs.mli index 3cdc7af0788..41fb780b04f 100644 --- a/src/docs/docs.mli +++ b/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 diff --git a/src/docs/extract.ml b/src/docs/extract.ml index 92cfffeca63..651e62d9d53 100644 --- a/src/docs/extract.ml +++ b/src/docs/extract.ml @@ -218,9 +218,10 @@ struct 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 skip_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 = diff --git a/src/exes/mo_doc.ml b/src/exes/mo_doc.ml index 1af31ce5ddf..1a30dedd23d 100644 --- a/src/exes/mo_doc.ml +++ b/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, " 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 From 055513c66569ca824ab0d3300813e12827038d1e Mon Sep 17 00:00:00 2001 From: Claudio Russo Date: Mon, 9 Dec 2024 11:54:53 +0000 Subject: [PATCH 2/2] add mo-doc option to strip comments --- doc/Makefile | 3 +++ src/docs/docs.ml | 12 ++++++------ src/docs/extract.ml | 24 ++++++++++++++++-------- 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index edb9018eef4..f34416b9dc6 100644 --- a/doc/Makefile +++ b/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 diff --git a/src/docs/docs.ml b/src/docs/docs.ml index b9262edcf3c..4101f1341a5 100644 --- a/src/docs/docs.ml +++ b/src/docs/docs.ml @@ -24,7 +24,7 @@ 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 -> @@ -32,7 +32,7 @@ let extract : bool -> string -> extracted option = 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,11 +91,11 @@ 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; @@ -103,14 +103,14 @@ let start : output_format -> string -> string -> bool -> unit = (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)) diff --git a/src/docs/extract.ml b/src/docs/extract.ml index 651e62d9d53..0385a350341 100644 --- a/src/docs/extract.ml +++ b/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,7 +103,7 @@ 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 @@ -105,7 +111,7 @@ struct { 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,7 +217,7 @@ struct { xref; doc_comment = - Trivia.doc_comment_of_trivia_info + doc_comment_of_trivia_info (Env.find_trivia dec_field.at); declaration = decl_doc; }) @@ -219,13 +225,12 @@ struct 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; }