Fix docstrings. NFC.

src/bin/iec_checker.ml

@@ -54,7 +54,7 @@ let parse_xml_file (filename : string) : parse_results =
   let (elements, warns) = parse_with_error lexbuf in
   (elements, warns)
 
-(** [parse_sel_xml_file] parses an SEL XML file located on [filepath]. If the
+(** [parse_sel_xml_file] Parse an SEL XML file located on [filepath]. If the
     file contains the valid XML, it returns parse results, otherwise None. *)
 let parse_sel_xml_file (filepath : string) : parse_results option =
   let inx = In_channel.create filepath in
@@ -75,7 +75,7 @@ let endswith s1 s2 =
     let sub = String.sub s1 ~pos:(len1 - len2) ~len:(len2) in
     String.equal sub s2
 
-(** [walkthrough_directory] recursively traverses [path] and returns absolute
+(** [walkthrough_directory] Recursively traverse [path] and return absolute
     paths to the files with the given [suffix]. *)
 let walkthrough_directory path suffix =
   let rec aux result = function
@@ -100,7 +100,7 @@ let walkthrough_directory path suffix =
   in
   aux [] [path]
 
-(** [get_files_to_check] returns a list of the files to be checked. *)
+(** [get_files_to_check] Return a list of the files to be checked. *)
 let get_files_to_check paths in_fmt =
   let suffix = match in_fmt with
     | InputST                -> ".st"
@@ -111,20 +111,20 @@ let get_files_to_check paths in_fmt =
     ~init:[]
     ~f:(fun acc p -> acc @ walkthrough_directory p suffix)
 
-(** [prepare_paths] determines which files will be parsed. *)
+(** [prepare_paths] Determine which files will be parsed. *)
 let prepare_paths paths in_fmt =
   if List.exists paths ~f:(fun p -> String.equal p "-") then
     ["-"]
   else
     get_files_to_check paths in_fmt
 
-(** [start_repl] starts the iec-checker REPL. *)
+(** [start_repl] Start the iec-checker REPL. *)
 let start_repl interactive =
   if interactive then Printf.printf "> ";
   Out_channel.flush stdout;
   parse_stdin ()
 
-(** [parse_file] parses file with the given path. *)
+(** [parse_file] Parse file with the given path. *)
 let parse_file path in_fmt verbose : parse_results option =
   if verbose then Printf.printf "Parsing %s ...\n" path;
   match in_fmt with
@@ -140,7 +140,7 @@ module ReturnCode = struct
   let not_found = 127
 end
 
-(** [run_checker] runs program on the file with [path] and returns the
+(** [run_checker] Run program on the file with [path] and returns the
     error code. *)
 let run_checker path in_fmt out_fmt create_dumps verbose (interactive : bool) : int =
   let (read_stdin : bool) = (String.equal "-" path) || (String.is_empty path) in

src/core/cfg.mli

@@ -23,15 +23,15 @@ type bb =
     mutable preds : int list; (** Ids of predecessor nodes *)
     mutable succs : int list; (** Ids of successor nodes *)
     (* TODO: This should be replaced with ids of statements. But it will
-     require additional symbol tables and a lot of refactoring in the parser. *)
+       require additional symbol tables and a lot of refactoring in the parser. *)
     mutable stmts : S.statement list [@opaque]; (** Statements that makes up this BB *)
   }
 
 val mk : S.iec_library_element -> t
-(** Create a new CFG instance for a given iec_library_element *)
+(** [mk] Create a new CFG instance for a given iec_library_element. *)
 
 val get_pou_id : t -> int
-(** Get the id of the POU that this CFG belongs to *)
+(** [get_pou_id] Get the id of the POU that this CFG belongs to. *)
 
 val get_bb_by_id_exn : t -> int -> bb
 (** [get_bb_by_id_exn id cfg] Return basic block stored in [cfg] by given ID.
@@ -49,13 +49,13 @@ val get_number_of_edges : t -> int
 (** [get_number_of_edges cfg] Return number of edges in [cfg]. *)
 
 val bb_by_id : t -> int -> bb option
-(** Get basic block entry from a given id. *)
+(** [bb_by_id] Get basic block entry from a given id. *)
 
 val bb_get_ti : bb -> TI.t
-(** Get token info for the basic block. *)
+(** [bb_get_ti] Get token info for the basic block. *)
 
 val create_cfgs : S.iec_library_element list -> t list
-(** Create list of CFGs for a given iec_library_element objects. *)
+(** [create_cfgs] Create list of CFGs for a given iec_library_element objects. *)
 
 val to_string : t -> string
 

src/core/config.mli

@@ -1,13 +1,13 @@
 (** Configuration values including platform and implementation dependent options. *)
 
-(** Maximum size of STRING and WSTRING data types. *)
 val max_string_len : int
+(** Maximum size of STRING and WSTRING data types. *)
 
-(** Threshold of McCabe complexity to generate warnings. *)
 val mccabe_complexity_threshold : int
+(** Threshold of McCabe complexity to generate warnings. *)
 
-(** Threshold of maximum number of statements in POU to generate warnings. *)
 val statements_num_threshold : int
+(** Threshold of maximum number of statements in POU to generate warnings. *)
 
 (* {{{ List of the enabled checks *)
 val check_plcopen_cp1 : bool

src/core/dump.mli

@@ -13,4 +13,4 @@ type dump_scheme = {
 } [@@deriving to_yojson]
 
 val create_dump : S.iec_library_element list -> Env.t list -> Cfg.t list -> string (** source filename *) -> unit
-(** Save input AST in a JSON file.  *)
+(** [create_dump] Save input AST in a JSON file.  *)

src/core/env.mli

@@ -14,24 +14,24 @@ module S = Syntax
 type t
 
 val get_id : t -> int
-(** Get the unique ID of the POU that this env belongs to. *)
+(** [get_id] Get the unique ID of the POU that this env belongs to. *)
 
 val empty : t
-(** Create an empty environment *)
+(** [empty] Create an empty environment *)
 
 val mk_global : unit -> t
-(** Make a new global environment. *)
+(** [mk_global] Make a new global environment. *)
 
 val mk : t (** parent environment *) -> int (** POU id *) -> t
-(** Add a new child environment *)
+(** [mk] Add a new child environment *)
 
 val add_vdecl : t -> S.VarDecl.t -> t
-(** Insert variable declaration in [t] *)
+(** [add_vdecl] Insert variable declaration in [t]. *)
 
 val get_vdecls : t -> S.VarDecl.t list
-(** Return variables declared in [t] *)
+(** [get_vdecls] Return variables declared in [t]. *)
 
 val lookup_vdecl : t -> string -> S.VarDecl.t option
-(** Search for a given identifier name in the given environment *)
+(** [lookup_vdecl] Search for a given identifier name in the given environment. *)
 
 val to_yojson : t -> Yojson.Safe.t

src/core/syntax.mli

@@ -629,10 +629,10 @@ val mk_pou : [< `Function of function_decl
              | `Type of derived_ty_decl ] -> iec_library_element
 
 val get_pou_id : iec_library_element -> int
-(** Get unique identifier of the given library element. *)
+(** [get_pou_id] Get unique identifier of the given library element. *)
 
 val get_pou_vars_decl : iec_library_element -> VarDecl.t list
-(** Return variables declared for the given POU. *)
+(** [get_pou_vars_decl] Return variables declared for the given POU. *)
 
 (* {{{ Yojson helpers *)
 val derived_ty_decl_to_yojson : derived_ty_decl -> Yojson.Safe.t

src/core/tok_info.mli

@@ -4,9 +4,9 @@ type t = { id : int; linenr : int; col : int } [@@deriving yojson, show]
 (** Parse tree item *)
 
 val create : Lexing.lexbuf -> t
-(** Create new parse tree element from Lexing.lexbuf *)
+(** [create] Create new parse tree element from Lexing.lexbuf *)
 
 val create_dummy : unit -> t
-(** Create a new dummy parse tree element *)
+(** [create_dummy] Create a new dummy parse tree element *)
 
 val to_string : t -> string

src/core/warn.mli

@@ -18,4 +18,3 @@ val mk_internal : ?id:(string) -> string -> t
 val mk_from_lexbuf : Lexing.lexbuf -> string -> string -> t
 
 val to_string : t -> string
-(** Converts warning to string *)

src/core/warn_output.mli

@@ -6,4 +6,4 @@ type output_format =
   | Json
 
 val print_report : W.t list -> output_format -> unit
-(** Print warnings in selected format to stdout. *)
+(** [print_report] Print warnings in selected format to stdout. *)

src/lib/checkerLib.mli

@@ -2,4 +2,4 @@ open IECCheckerCore
 module S = Syntax
 
 val run_all_checks : S.iec_library_element list -> Env.t list -> Cfg.t list -> bool -> Warn.t list
-(** Run all available checks *)
+(** [run_all_checks] Run all available checks *)