Skip to content

Use Comment.elements in document and index #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

### Added

- Addded `--suppress-warnings` to the CLI to remove warnings from a unit, even
if they end up being raised in another unit through expansion (@jonludlam,
#1260)
- Improve jump to implementation in rendered source code, and add a
`count-occurrences` flag and command to count occurrences of every identifiers
(@panglesd, #976)
Expand Down
2 changes: 0 additions & 2 deletions doc/examples/resolution.mli
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,6 @@ module Hidden : sig
(**/**)

type v = T of t

type w = U of u
end

module References : sig
Expand Down
4 changes: 1 addition & 3 deletions doc/odoc.mld
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,4 @@ The main other pages of this site:
- {!page-ocamldoc_differences} outlines differences from OCamldoc.
- {!page-dune} shows how to create docs using Dune.
- {!page-parent_child_spec} delineates parent/child specifications.
- {!page-interface} describes [odoc]'s public-facing interface and their support guarantees.
- {!page-ocamlary} demonstrates the rendering of most of the OCaml constructs.
- {!page-api_reference} lists [odoc]'s API reference library.
- {!page-interface} describes [odoc]'s public-facing interface and their support guarantees.
5 changes: 5 additions & 0 deletions dune
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,8 @@
(progn
(bash "diff doc/driver.mld doc/driver.mld.corrected >&2 || true")
(cat doc/driver-benchmarks.json))))

(install
(files odoc-config.sexp)
(section doc)
(package odoc))
2 changes: 2 additions & 0 deletions odoc-config.sexp
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
(libraries fmt)

4 changes: 2 additions & 2 deletions src/document/comment.ml
Original file line number Diff line number Diff line change
Expand Up @@ -413,8 +413,8 @@ let standalone docs =
Utils.flatmap ~f:item_element
@@ List.map (fun x -> x.Odoc_model.Location_.value) docs

let to_ir (docs : Comment.docs) =
let to_ir (docs : Comment.elements) =
Utils.flatmap ~f:block_element
@@ List.map (fun x -> x.Odoc_model.Location_.value) docs.elements
@@ List.map (fun x -> x.Odoc_model.Location_.value) docs

let has_doc docs = docs <> []
38 changes: 18 additions & 20 deletions src/document/generator.ml
Original file line number Diff line number Diff line change
Expand Up @@ -530,10 +530,9 @@ module Make (Syntax : SYNTAX) = struct
field fld.mutable_ (fld.id :> Paths.Identifier.t) fld.type_
in
let anchor = Some url in
let rhs = Comment.to_ir fld.doc in
let doc =
if not (Comment.has_doc fld.doc.elements) then [] else rhs
in
let doc = fld.doc.elements in
let rhs = Comment.to_ir doc in
let doc = if not (Comment.has_doc doc) then [] else rhs in
let markers = Syntax.Comment.markers in
DocumentedSrc.Documented { anchor; attrs; code; doc; markers })
in
Expand Down Expand Up @@ -610,10 +609,9 @@ module Make (Syntax : SYNTAX) = struct
cstr.args cstr.res
in
let anchor = Some url in
let rhs = Comment.to_ir cstr.doc in
let doc =
if not (Comment.has_doc cstr.doc.elements) then [] else rhs
in
let doc = cstr.doc.elements in
let rhs = Comment.to_ir doc in
let doc = if not (Comment.has_doc doc) then [] else rhs in
let markers = Syntax.Comment.markers in
DocumentedSrc.Nested { anchor; attrs; code; doc; markers })
in
Expand All @@ -625,7 +623,7 @@ module Make (Syntax : SYNTAX) = struct
let anchor = Some url in
let attrs = [ "def"; "variant"; Url.Anchor.string_of_kind url.kind ] in
let code = O.documentedSrc (O.txt "| ") @ constructor id t.args t.res in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
let markers = Syntax.Comment.markers in
DocumentedSrc.Nested { anchor; attrs; code; doc; markers }

Expand All @@ -646,7 +644,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "type"; "extension" ] in
let anchor = Some (Url.Anchor.extension_decl t) in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
let source_anchor =
(* Take the anchor from the first constructor only for consistency with
regular variants. *)
Expand All @@ -666,7 +664,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "exception" ] in
let anchor = path_to_id t.id in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
let source_anchor = source_anchor t.source_loc in
Item.Declaration { attr; anchor; doc; content; source_anchor }

Expand Down Expand Up @@ -710,7 +708,7 @@ module Make (Syntax : SYNTAX) = struct
else O.txt " " ++ O.keyword "of" ++ O.sp ++ params)),
match doc with
| { elements = []; _ } -> None
| _ -> Some (Comment.to_ir doc) ))
| _ -> Some (Comment.to_ir doc.elements) ))
in
let markers = Syntax.Comment.markers in
try
Expand Down Expand Up @@ -881,7 +879,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = "type" :: (if is_substitution then [ "subst" ] else []) in
let anchor = path_to_id t.id in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
let source_anchor = source_anchor t.source_loc in
Item.Declaration { attr; anchor; doc; content; source_anchor }
end
Expand Down Expand Up @@ -909,7 +907,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "value" ] @ extra_attr in
let anchor = path_to_id t.id in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
let source_anchor = source_anchor t.source_loc in
Item.Declaration { attr; anchor; doc; content; source_anchor }
end
Expand Down Expand Up @@ -1010,7 +1008,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "method" ] in
let anchor = path_to_id t.id in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
Item.Declaration { attr; anchor; doc; content; source_anchor = None }

let instance_variable (t : Odoc_model.Lang.InstanceVariable.t) =
Expand All @@ -1029,7 +1027,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "value"; "instance-variable" ] in
let anchor = path_to_id t.id in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
Item.Declaration { attr; anchor; doc; content; source_anchor = None }

let inherit_ (ih : Lang.ClassSignature.Inherit.t) =
Expand All @@ -1043,7 +1041,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "inherit" ] in
let anchor = None in
let doc = Comment.to_ir ih.doc in
let doc = Comment.to_ir ih.doc.elements in
Item.Declaration { attr; anchor; doc; content; source_anchor = None }

let constraint_ (cst : Lang.ClassSignature.Constraint.t) =
Expand All @@ -1052,7 +1050,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [] in
let anchor = None in
let doc = Comment.to_ir cst.doc in
let doc = Comment.to_ir cst.doc.elements in
Item.Declaration { attr; anchor; doc; content; source_anchor = None }

let class_signature (c : Lang.ClassSignature.t) =
Expand Down Expand Up @@ -1314,7 +1312,7 @@ module Make (Syntax : SYNTAX) = struct
in
let attr = [ "module-substitution" ] in
let anchor = path_to_id t.id in
let doc = Comment.to_ir t.doc in
let doc = Comment.to_ir t.doc.elements in
Item.Declaration { attr; anchor; doc; content; source_anchor = None }

and module_type_substitution (t : Odoc_model.Lang.ModuleTypeSubstitution.t)
Expand Down Expand Up @@ -1724,7 +1722,7 @@ module Make (Syntax : SYNTAX) = struct
synopsis because no page is generated to render it and we'd loose
the full documentation.
The documentation from the expansion is not used. *)
Comment.to_ir t.doc
Comment.to_ir t.doc.elements
in
Item.Include { attr; anchor; doc; content; source_anchor = None }
end
Expand Down
2 changes: 1 addition & 1 deletion src/document/sidebar.ml
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ end = struct
| Page { short_title = None; _ } ->
let title =
let open Odoc_model in
match Comment.find_zero_heading entry.doc.elements with
match Comment.find_zero_heading entry.doc with
| Some t -> t
| None ->
let name =
Expand Down
3 changes: 2 additions & 1 deletion src/driver/landing_pages.ml
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,14 @@ let make_index ~dirs ?pkg ~rel_dir ?index ~content () =
let odoc_file = Fpath.(odoc_dir // rel_dir / "page-index.odoc") in
let odocl_file = Fpath.(odocl_dir // rel_dir / "page-index.odocl") in
let parent_id = rel_dir |> Odoc.Id.of_fpath in
let pkg_args = Pkg_args.v ~pages ~libs ~odoc_dir ~odocl_dir in
Util.with_out_to input_file (fun oc ->
fpf (Format.formatter_of_out_channel oc) "%t@?" content)
|> Result.get_ok;
{
output_dir = dirs.odoc_dir;
pkgname = None;
pkg_args = { Pkg_args.pages; libs; odoc_dir; odocl_dir };
pkg_args;
parent_id;
input_file;
odoc_file;
Expand Down
20 changes: 14 additions & 6 deletions src/driver/odoc_unit.ml
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,16 @@ module Pkg_args = struct
type t = {
odoc_dir : Fpath.t;
odocl_dir : Fpath.t;
pages : (string * Fpath.t) list;
libs : (string * Fpath.t) list;
pages : Fpath.t Util.StringMap.t;
libs : Fpath.t Util.StringMap.t;
}

let map_rel dir = List.map (fun (a, b) -> (a, Fpath.(dir // b)))
let v ~odoc_dir ~odocl_dir ~pages ~libs =
let pages, libs = Util.StringMap.(of_list pages, of_list libs) in
{ odoc_dir; odocl_dir; pages; libs }

let map_rel dir m =
Util.StringMap.fold (fun a b acc -> (a, Fpath.(dir // b)) :: acc) m []

let compiled_pages v = map_rel v.odoc_dir v.pages
let compiled_libs v = map_rel v.odoc_dir v.libs
Expand All @@ -21,8 +26,8 @@ module Pkg_args = struct
{
odoc_dir = v1.odoc_dir;
odocl_dir = v1.odocl_dir;
pages = v1.pages @ v2.pages;
libs = v1.libs @ v2.libs;
pages = Util.StringMap.union (fun _ x _ -> Some x) v1.pages v2.pages;
libs = Util.StringMap.union (fun _ x _ -> Some x) v1.libs v2.libs;
}

let pp fmt x =
Expand All @@ -33,7 +38,10 @@ module Pkg_args = struct
in
Format.fprintf fmt
"@[<hov>odoc_dir: %a@;odocl_dir: %a@;pages: [%a]@;libs: [%a]@]" Fpath.pp
x.odoc_dir Fpath.pp x.odocl_dir sfp_pp x.pages sfp_pp x.libs
x.odoc_dir Fpath.pp x.odocl_dir sfp_pp
(Util.StringMap.bindings x.pages)
sfp_pp
(Util.StringMap.bindings x.libs)
end

type sidebar = { output_file : Fpath.t; json : bool }
Expand Down
14 changes: 8 additions & 6 deletions src/driver/odoc_unit.mli
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
module Pkg_args : sig
type t = {
odoc_dir : Fpath.t;
odocl_dir : Fpath.t;
pages : (string * Fpath.t) list;
libs : (string * Fpath.t) list;
}
type t

val compiled_pages : t -> (string * Fpath.t) list
val compiled_libs : t -> (string * Fpath.t) list
val linked_pages : t -> (string * Fpath.t) list
val linked_libs : t -> (string * Fpath.t) list

val v :
odoc_dir:Fpath.t ->
odocl_dir:Fpath.t ->
pages:(string * Fpath.t) list ->
libs:(string * Fpath.t) list ->
t

val combine : t -> t -> t

val pp : t Fmt.t
Expand Down
13 changes: 8 additions & 5 deletions src/driver/odoc_units_of.ml
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ let packages ~dirs ~extra_paths ~remap (pkgs : Packages.t list) : t list =
let base_args pkg lib_deps : Pkg_args.t =
let own_page = dash_p pkg.Packages.name (doc_dir pkg) in
let own_libs = List.concat_map dash_l (Util.StringSet.to_list lib_deps) in
{ pages = [ own_page ]; libs = own_libs; odoc_dir; odocl_dir }
Pkg_args.v ~pages:[ own_page ] ~libs:own_libs ~odoc_dir ~odocl_dir
in
let args_of_config config : Pkg_args.t =
let { Global_config.deps = { packages; libraries } } = config in
Expand All @@ -61,7 +61,7 @@ let packages ~dirs ~extra_paths ~remap (pkgs : Packages.t list) : t list =
packages
in
let libs_rel = List.concat_map dash_l libraries in
{ pages = pages_rel; libs = libs_rel; odoc_dir; odocl_dir }
Pkg_args.v ~pages:pages_rel ~libs:libs_rel ~odoc_dir ~odocl_dir
in
let args_of =
let cache = Hashtbl.create 10 in
Expand Down Expand Up @@ -193,10 +193,13 @@ let packages ~dirs ~extra_paths ~remap (pkgs : Packages.t list) : t list =
in
let of_lib pkg (lib : Packages.libty) =
let lib_deps = Util.StringSet.add lib.lib_name lib.lib_deps in
let landing_page :> t =
let index = index_of pkg in
Landing_pages.library ~dirs ~pkg ~index lib
let lib_deps =
List.fold_left
(fun acc lib -> Util.StringSet.add lib.Packages.lib_name acc)
lib_deps pkg.Packages.libraries
in
let index = index_of pkg in
let landing_page :> t = Landing_pages.library ~dirs ~pkg ~index lib in
landing_page :: List.concat_map (of_module pkg lib lib_deps) lib.modules
in
let of_mld pkg (mld : Packages.mld) : mld unit list =
Expand Down
2 changes: 1 addition & 1 deletion src/index/entry.ml
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ type kind =

type t = {
id : Odoc_model.Paths.Identifier.Any.t;
doc : Odoc_model.Comment.docs;
doc : Odoc_model.Comment.elements;
kind : kind;
}

Expand Down
4 changes: 2 additions & 2 deletions src/index/entry.mli
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,12 @@ type kind =

type t = {
id : Odoc_model.Paths.Identifier.Any.t;
doc : Odoc_model.Comment.docs;
doc : Odoc_model.Comment.elements;
kind : kind;
}

val entry :
id:[< Odoc_model.Paths.Identifier.Any.t_pv ] Odoc_model.Paths.Identifier.id ->
doc:Odoc_model.Comment.docs ->
doc:Odoc_model.Comment.elements ->
kind:kind ->
t
Loading
Loading