Skip to content

Parsing of path-references to pages and modules #1142

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.

Sign up for GitHub

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

Merged
merged 11 commits into from
Jul 10, 2024
Merged

Parsing of path-references to pages and modules #1142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
481af7f
Parse path-references
Julow Jun 4, 2024
b6e46ce
Test parsing of path-references
Julow Jun 5, 2024
175e93f
Mention paths in 'expected' reference parsing errors
Julow Jun 7, 2024
861d61b
Allow prefixed page reference
Julow Jun 7, 2024
75a9ac6
Update Changes
Julow Jun 7, 2024
559a773
Represent path references as a tag and component list
Julow Jul 8, 2024
2fa7483
Represent page and module paths
Julow Jul 9, 2024
d655956
Rename Reference.Path into Reference.Hierarchy
Julow Jul 9, 2024
4b2c293
Add canonical tags to tag_any and tag_hierarchy
Julow Jul 10, 2024
e66ecbd
Parsing error on path-reference with empty components
Julow Jul 10, 2024
fcaa46e
Remove unreachable cases
Julow Jul 10, 2024
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
2 changes: 1 addition & 1 deletion CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
- OCaml 5.2.0 compatibility (@Octachron, #1094, #1112)
- New driver package (@jonludlam, #1121)
- Fix a big gap between the preamble and the content of a page (@EmileTrotignon, #1147)
- Path-references to hierarchical pages and modules (@Julow, #1151)
- Path-references to hierarchical pages and modules (@Julow, #1142, #1151)
Absolute (`{!/foo}`), relative (`{!./foo}`) and package-local (`{!//foo}`)
are added.
- Add a marshalled search index consumable by sherlodoc (@EmileTrotignon, @panglesd, #1084)
Expand Down
12 changes: 12 additions & 0 deletions src/document/comment.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,24 @@ module Reference = struct
render_resolved (r :> t) ^ "." ^ InstanceVariableName.to_string s
| `Label (_, s) -> LabelName.to_string s

let render_path (tag, cs) =
let tag =
match tag with
| `TRelativePath -> "./"
| `TAbsolutePath -> "/"
| `TCurrentPackage -> "//"
in
tag ^ String.concat "/" cs

let rec render_unresolved : Reference.t -> string =
let open Reference in
function
| `Resolved r -> render_resolved r
| `Root (n, _) -> n
| `Dot (p, f) -> render_unresolved (p :> t) ^ "." ^ f
| `Page_path p -> render_path p
| `Module_path p -> render_path p
| `Any_path p -> render_path p
| `Module (p, f) ->
render_unresolved (p :> t) ^ "." ^ ModuleName.to_string f
| `ModuleType (p, f) ->
Expand Down
5 changes: 5 additions & 0 deletions src/model/paths.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1092,6 +1092,7 @@ module Reference = struct
type t = Paths_types.Reference.any

type tag_any = Paths_types.Reference.tag_any
type tag_hierarchy = Paths_types.Reference.tag_hierarchy

module Signature = struct
type t = Paths_types.Reference.signature
Expand Down Expand Up @@ -1172,4 +1173,8 @@ module Reference = struct
module Page = struct
type t = Paths_types.Reference.page
end

module Hierarchy = struct
type t = Paths_types.Reference.hierarchy
end
end
5 changes: 5 additions & 0 deletions src/model/paths.mli
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,12 @@ module rec Reference : sig
type t = Paths_types.Reference.page
end

module Hierarchy : sig
type t = Paths_types.Reference.hierarchy
end

type t = Paths_types.Reference.any

type tag_any = Paths_types.Reference.tag_any
type tag_hierarchy = Paths_types.Reference.tag_hierarchy
end
22 changes: 21 additions & 1 deletion src/model/paths_types.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -553,6 +553,12 @@ module rec Reference : sig

type tag_only_child_module = [ `TChildModule ]

type tag_hierarchy =
[ `TRelativePath (** {!identifier/} *)
| `TAbsolutePath (** {!/identifier} *)
| `TCurrentPackage (** {!//identifier} *) ]
(** @canonical Odoc_model.Paths.Reference.tag_hierarchy *)

type tag_any =
[ `TModule
| `TModuleType
Expand All @@ -572,6 +578,7 @@ module rec Reference : sig
| `TChildPage
| `TChildModule
| `TUnknown ]
(** @canonical Odoc_model.Paths.Reference.tag_any *)

type tag_signature = [ `TUnknown | `TModule | `TModuleType ]

Expand All @@ -592,10 +599,14 @@ module rec Reference : sig
| `TChildPage
| `TChildModule ]

type hierarchy = tag_hierarchy * string list
(** @canonical Odoc_model.Paths.Reference.Hierarchy.t *)

type signature =
[ `Resolved of Resolved_reference.signature
| `Root of string * tag_signature
| `Dot of label_parent * string
| `Module_path of hierarchy
| `Module of signature * ModuleName.t
| `ModuleType of signature * ModuleTypeName.t ]
(** @canonical Odoc_model.Paths.Reference.Signature.t *)
Expand All @@ -620,6 +631,7 @@ module rec Reference : sig
[ `Resolved of Resolved_reference.field_parent
| `Root of string * tag_parent
| `Dot of label_parent * string
| `Module_path of hierarchy
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Module path can only be of the form: /libname/. For example: {!/libname/module-M.type-t}.

I think that could be reflected in the type?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess that #1142 (comment) answers no to the question!

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this can happen with {!/M.type-t}. I'm not in favor of enforcing that in the parser. The resolver has to match on the path to be able to lookup libname, that's where the reference should be rejected.

| `Module of signature * ModuleName.t
| `ModuleType of signature * ModuleTypeName.t
| `Type of signature * TypeName.t ]
Expand All @@ -629,6 +641,9 @@ module rec Reference : sig
[ `Resolved of Resolved_reference.label_parent
| `Root of string * tag_label_parent
| `Dot of label_parent * string
| `Page_path of hierarchy
| `Module_path of hierarchy
| `Any_path of hierarchy
| `Module of signature * ModuleName.t
| `ModuleType of signature * ModuleTypeName.t
| `Class of signature * ClassName.t
Expand All @@ -640,6 +655,7 @@ module rec Reference : sig
[ `Resolved of Resolved_reference.module_
| `Root of string * [ `TModule | `TUnknown ]
| `Dot of label_parent * string
| `Module_path of hierarchy
| `Module of signature * ModuleName.t ]
(** @canonical Odoc_model.Paths.Reference.Module.t *)

Expand Down Expand Up @@ -743,13 +759,17 @@ module rec Reference : sig
type page =
[ `Resolved of Resolved_reference.page
| `Root of string * [ `TPage | `TUnknown ]
| `Dot of label_parent * string ]
| `Dot of label_parent * string
| `Page_path of hierarchy ]
(** @canonical Odoc_model.Paths.Reference.Page.t *)

type any =
[ `Resolved of Resolved_reference.any
| `Root of string * tag_any
| `Dot of label_parent * string
| `Page_path of hierarchy
| `Module_path of hierarchy
| `Any_path of hierarchy
| `Module of signature * ModuleName.t
| `ModuleType of signature * ModuleTypeName.t
| `Type of signature * TypeName.t
Expand Down
Loading
Loading