diff --git a/DESIGN_SHOW.md b/DESIGN_SHOW.md index 205a519..2373d3c 100644 --- a/DESIGN_SHOW.md +++ b/DESIGN_SHOW.md @@ -33,7 +33,8 @@ roots, see below — `Url.resolve` passes `~roots:None`): ```ocaml let resolver = - Resolver.create ~important_digests:false ~directories ~open_modules:[] ~roots + Resolver.create ~important_digests:false ~directories + ~open_modules:["Stdlib"] ~roots in let reference = Odoc_model.Semantics.parse_reference s (* string -> Reference.t *) @@ -49,6 +50,12 @@ Odoc_xref2.Ref_tools.resolve_reference env reference `Identifier.t` of the target (the same step `url.ml` feeds to `Document.Url.from_identifier`). +`~open_modules:["Stdlib"]` makes resolution behave as if `open Stdlib`, so a +bare `List` or `print_endline` resolves — mirroring the compiler's (and the +driver's link-time) default environment. `Env.open_units` looks each name up +through the resolver and opens its signature; a module not documented in the +switch is silently skipped. + Note the second element of the result is only a *synopsis* paragraph (the first paragraph, used when expanding `{!ref}` inline). We want the whole doc comment, so we ignore it and fetch the docs separately. diff --git a/README.md b/README.md index 6652ccc..a9b2f9e 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,9 @@ $ switchdocs setup --apply # add it to ~/.opam/config via `opam option` single query covers the whole switch), printing each match with its owning package. `--package` restricts to named packages. - `switchdocs show REFERENCE` — print an item's documentation as Markdown, - resolving an odoc reference (e.g. `Stdlib.List.map`, `Astring.String`, or a - package-qualified `/stdlib/Stdlib.List.map`) against the whole switch. + resolving an odoc reference against the whole switch. `Stdlib` is open, so + bare names work (`List`, `print_endline`); references may also be qualified + (`Astring.String`) or package-qualified (`/stdlib/Stdlib.List.map`). ## Development diff --git a/lib/show.ml b/lib/show.ml index 81f528a..951708b 100644 --- a/lib/show.ml +++ b/lib/show.ml @@ -86,6 +86,12 @@ let scan sw = (* {1 Stage 2: resolve the reference} *) +(* Resolve references as if these modules were open, mirroring the compiler's + (and the driver's link-time) default environment, so a bare [List] reaches + [Stdlib.List]. If a module isn't documented in the switch, [open_units] + simply skips it. *) +let default_open = [ "Stdlib" ] + let resolve_to_id { odoc; directories; page_roots; lib_roots; _ } ref_str = let dir = Odoc_odoc.Fs.Directory.of_string in let directories = List.map (fun d -> dir (Fpath.to_string d)) directories in @@ -106,7 +112,7 @@ let resolve_to_id { odoc; directories; page_roots; lib_roots; _ } ref_str = in let resolver = Odoc_odoc.Resolver.create ~important_digests:false ~directories - ~open_modules:[] ~roots + ~open_modules:default_open ~roots in let warnings_options = {