Ocamldoc - how to accesss special comments when writing a custom generator?

Ecosystem
,
1

Hello,

I’m trying to make my own ocamldoc generator, and I’m having trouble finding where the actual “special comments” are.

I have the following experiment code, to try and access all sorts of elements, mostly constructed from reading the ocamldoc source code. The thing is, that non of these things even remotely gave me an idea how to access the special comments. Reading the examples like html and others, didn’t help too much.

Any resource to where get an example or documentation of the data-structure of the module_list is welcomed.

For now I have one question: How do I access the special comments?

Thanks!

Warning: messy code, just trying out stuff.

let string_of_val_info (info: Odoc_types.info) =
  info.i_authors

let param_to_string_list params =
  List.map
    (fun param ->
      match param with
      | (s, t) -> s
    )
    params

let string_of_param (info: Odoc_types.info) =
  param_to_string_list info.i_params

let return_value_to_string return_values =
  String.concat ", "
    (List.map
      (fun return_value ->
        (match return_value with | Odoc_types.Raw s -> s | _ -> "other")
      )
      return_values
    )

let string_of_return_value (info: Odoc_types.info) =
  match info.i_return_value with
    | Some ret_val -> [return_value_to_string ret_val]
    | None -> ["nonono"]

let text_to_string (text: Odoc_types.text option) =
  match text with
  | Some text -> "sfhj"
  | None -> "Unknown"

let rec string_of_parameters parameters =
  List.map
    (fun param ->
      match param with
        | Odoc_parameter.Simple_name simple_name ->
              "(" ^ simple_name.sn_name ^ ": " ^ (text_to_string simple_name.sn_text) ^ ")"
        | param_info_list -> "string_of_parameters param_info_list"
    )
    parameters

let string_of_custum_stuff (info: Odoc_types.info) =
    List.map
    (fun pair -> match pair with | (str, txt) -> str | _ -> "What??")
    info.i_custom

module Generator (G : Odoc_html.Html_generator) =
struct
  class html =
    object(self)
      inherit G.html

      method generate module_list =
        Printf.printf "---------------------------------------------------------------- Values:\n";
        List.map
          (fun (v: Odoc_info.Value.t_value) ->
            Printf.printf "%s\n" v.val_name;
            match v.val_info with
            | Some info ->
              Printf.printf
                "%s\n  %s\n  %s\n  %s\n  %s\n"
                v.val_name
                (String.concat ", " (string_of_val_info info))
                (String.concat ", " (string_of_param info))
                (String.concat ", " (string_of_return_value info))
                (String.concat ", " (string_of_custum_stuff info))
            | None -> Printf.printf " - No info to see, please move on.\n";
            match (List.length v.val_parameters) with
            | 0 -> Printf.printf " - No parameters to see, please move on.\n";
            | _ -> Printf.printf " - %s\n" (String.concat ", " (string_of_parameters v.val_parameters));
            match v.val_code with
            | Some s -> Printf.printf " - %s\n" s;
            | None -> Printf.printf " - No val_code to see, please move on.\n";
          )
          (Odoc_info.Search.values module_list);
        Printf.printf "---------------------------------------------------------------- Methods:\n";
        List.map
          (fun (v: Odoc_info.Value.t_method) ->
            let something = v.met_value in
            Printf.printf "%s private: %s\n" something.val_name (if v.met_private then "private" else "public");
            match something.val_info with
            | Some info ->
              Printf.printf
                "%s\n  %s\n  %s\n  %s\n  %s\n"
                something.val_name
                (String.concat ", " (string_of_val_info info))
                (String.concat ", " (string_of_param info))
                (String.concat ", " (string_of_return_value info))
                (String.concat ", " (string_of_custum_stuff info));
                Printf.printf " - %s\n" (String.concat ", " (string_of_parameters something.val_parameters))
            | None -> ();
          )
          (Odoc_info.Search.methods module_list);
        Printf.printf "mathods.legth: %d\n" (List.length (Odoc_info.Search.methods module_list));
        Printf.printf "---------------------------------------------------------------- Classes:\n";
        List.map
        (fun (v: Odoc_info.Class.t_class) ->
          Printf.printf "%s\n" v.cl_name;
        )
        (Odoc_info.Search.classes module_list);
        Printf.printf "classes.legth: %d\n" (List.length (Odoc_info.Search.classes module_list));

        Printf.printf "---------------------------------------------------------------- Attributes:\n";
        (fun (v: Odoc_info.Value.t_attribute list) ->
          List.map
          (fun (a: Odoc_info.Value.t_attribute) -> Printf.printf "%s\n" a.att_value.val_name)
          v;
        )
        (Odoc_info.Search.attributes module_list);
        Printf.printf "attributes.legth: %d\n" (List.length (Odoc_info.Search.attributes module_list));
        ()

      initializer
        print_endline "Hallo!";
  end
end
let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;
2

Ocamldoc has been in maintenance-only mode for many years. Odoc is the much more reliable and future-proof current document generator. If odoc is not covering your need, it is probably better to open an issue on odoc bug tracker.

Moreover, I fear that writing custom generator for ocamldoc will not be future-proof at all. In particular, the support for such generator is the kind of features that I am thinking of eventually dropping at some point to ease the maintenance burden once ocamldoc is fully deprecated.

Now to answer your question, ocamldoc generator works on ocamldoc AST, the parsing and analysis of documentation comments has already been done at this point. Generators only define how this AST is printed in the different backends.