Extract documentation header information from ReScript modules

[ryyppy]

As previously discussed, there seems to be a very straightforward way to extract the ocaml.doc attributes from compiled ReScript modules without relying on more extensive tools (like odoc etc).

I'd need some pointers on where to start so I can extract all the information needed for our rescript-lang API docs.

[bobzhang]

hi @ryyppy , below is a small snippet (to just get you started), the idea is that you dump the docs into a json file and process it using your favorite tools

#!/usr/bin/env ocaml -I +compiler-libs ocamlcommon.cma

(* could use Ast_iterator for in depth traversing *)
open Format

let extract_doc (x : Parsetree.signature_item) = 
    match x.psig_desc with
    | Psig_value {pval_attributes; pval_name; _} 
      -> 
      begin  List.iter (fun ((id,payload) : Parsetree.attribute) -> 
        match id.txt, payload with 
        | "ocaml.doc", PStr [{pstr_desc = Pstr_eval ({pexp_desc = Pexp_constant (Pconst_string(a,_));_},_); _}]
          -> 
          printf "@[<v>%s:@ @[%s@]@]@." pval_name.txt a
        | _ -> ()   
       ) pval_attributes 
      end
   | _ -> ()    

let extract_docs (xs : Parsetree.signature) =
  List.iter extract_doc xs 
  
  
let extract_file fname = 
  let chan  = open_in_bin fname in 
  let lexbuf = Lexing.from_channel chan in 
  let signature = Parse.interface lexbuf in 
  extract_docs signature

let () =   
  for i = 0 to Array.length Sys.argv - 1 do 
    if Sys.argv.(i) = "-file" && i + 1 < Array.length Sys.argv then begin 
      extract_file Sys.argv.(i+1);
      exit 0
    end
  done     

An example output is:

res-doc$./main.ml -file ../bucklescript/jscomp/others/belt_List.mli 

setAssoc:
 [setAssoc xs k v eq]
    if [k] exists in [xs] by satisfying the [eq] predicate, return a new list
    with the key and value replaced by the new [k] and [v]; otherwise, return a new
    list with the pair [k, v] added to the head of [xs].
    @example {[
      setAssoc [1,"a"; 2, "b"; 3, "c"] 2 "x" (=) =
      [1,"a"; 2, "x"; 3,"c"] ;; 

      setAssoc [1,"a"; 3, "c"] 2 "b" (=) = 
      [2,"b"; 1,"a"; 3, "c"]
      
      setAssoc [9, "morning"; 3, "morning?!"; 22, "night"] 15 "afternoon"
        (fun a b -> a mod 12 = b mod 12) = [9, "morning"; 15, "afternoon"; 22, "night"]
    ]}
    
    Note carefully the last example! Since [15 mod 12] equals [3 mod 12], {i both} the key and value are
    replaced in the list.

sort:
 [sort xs]
    Returns a sorted list.
    @example {[
      sort [5; 4; 9; 3; 7] (fun a b -> a - b) = [3; 4; 5; 7; 9]
    ]}

...

[bobzhang]

code snippet is provided as above

[ryyppy]

thanks, already working on the extraction based on your example 👍