Skip to content

Commit 214c363

Browse files
JulowJulow
authored
Update vendored odoc-parser to master branch (#2632)
* Add support for media elements * Support for the new tag syntax and new tags * Backport changed newline parsing in code spans * Wrap code spans if they are too long If a code span exceed the margin, the line is broken before the code spans. If a code span is on its own line and still break the margin, then it is allowed to break. The new parsing rules allow us to do that without changing the comment.
1 parent 222bf26 commit 214c363

20 files changed

+522
-129
lines changed

Diff for: ‎CHANGES.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ profile. This started with version 0.26.0.
5656
- Added back the flag `--disable-outside-detected-project` (#2439, @gpetiot)
5757
It was removed in version 0.22.
5858

59-
- Support newer Odoc syntax (#2631, @Julow)
59+
- Support newer Odoc syntax (#2631, #2632, @Julow)
6060

6161
### Changed
6262

Diff for: ‎lib/Docstring.ml

+23-6
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,17 @@ let alignment_to_string = function
9696

9797
let header_data_to_string = function `Header -> "Header" | `Data -> "Data"
9898

99-
let rec odoc_nestable_block_element c fmt = function
99+
let media_to_string = function
100+
| `Audio -> "Audio"
101+
| `Video -> "Video"
102+
| `Image -> "Image"
103+
104+
let fmt_media_href fmt = function
105+
| `Reference s -> fpf fmt "Reference(%s)" s
106+
| `Link s -> fpf fmt "Link(%s)" s
107+
108+
let rec odoc_nestable_block_element c fmt : Ast.nestable_block_element -> _ =
109+
function
100110
| `Paragraph elms -> fpf fmt "Paragraph(%a)" odoc_inline_elements elms
101111
| `Code_block (b : Ast.code_block) ->
102112
let fmt_metadata fmt (m : Ast.code_block_meta) =
@@ -133,20 +143,24 @@ let rec odoc_nestable_block_element c fmt = function
133143
let pp_alignment = option (list (option pp_align)) in
134144
fpf fmt "Table((%a,%a),%s)" pp_grid grid pp_alignment alignment
135145
(light_heavy_to_string syntax)
146+
| `Media (_kind, href, text, media) ->
147+
fpf fmt "Media(%a,%S,%s)" (ign_loc fmt_media_href) href text
148+
(media_to_string media)
136149

137150
and odoc_nestable_block_elements c fmt elems =
138151
list (ign_loc (odoc_nestable_block_element c)) fmt elems
139152

140-
let odoc_tag c fmt = function
153+
let odoc_implicitly_ended_tag c fmt tag elems =
154+
fpf fmt "%s(%a)" tag (odoc_nestable_block_elements c) elems
155+
156+
let odoc_tag c fmt : Ast.tag -> unit = function
141157
| `Author txt -> fpf fmt "Author(%a)" str txt
142-
| `Deprecated elems ->
143-
fpf fmt "Deprecated(%a)" (odoc_nestable_block_elements c) elems
158+
| `Deprecated elems -> odoc_implicitly_ended_tag c fmt "Deprecated" elems
144159
| `Param (p, elems) ->
145160
fpf fmt "Param(%a,%a)" str p (odoc_nestable_block_elements c) elems
146161
| `Raise (p, elems) ->
147162
fpf fmt "Raise(%a,%a)" str p (odoc_nestable_block_elements c) elems
148-
| `Return elems ->
149-
fpf fmt "Return(%a)" (odoc_nestable_block_elements c) elems
163+
| `Return elems -> odoc_implicitly_ended_tag c fmt "Return" elems
150164
| `See (kind, txt, elems) ->
151165
let kind =
152166
match kind with `Url -> "U" | `File -> "F" | `Document -> "D"
@@ -163,6 +177,9 @@ let odoc_tag c fmt = function
163177
| `Open -> fpf fmt "Open"
164178
| `Closed -> fpf fmt "Closed"
165179
| `Hidden -> fpf fmt "Hidden"
180+
| `Children_order elems ->
181+
odoc_implicitly_ended_tag c fmt "Children_order" elems
182+
| `Short_title elems -> odoc_implicitly_ended_tag c fmt "Short_title" elems
166183

167184
let odoc_block_element c fmt = function
168185
| `Heading (lvl, lbl, content) ->

Diff for: ‎lib/Fmt_odoc.ml

+31-7
Original file line numberDiff line numberDiff line change
@@ -104,8 +104,15 @@ let fmt_verbatim_block ~loc s =
104104
in
105105
hvbox 0 (wrap (str "{v") (str "v}") content)
106106

107-
let fmt_code_span s =
108-
wrap (str "[") (str "]") (str (escape_balanced_brackets s))
107+
let fmt_code_span ~wrap s =
108+
let s = escape_balanced_brackets s in
109+
let s =
110+
if wrap then
111+
let words = String.split_on_chars ~on:[' '] s in
112+
list words space_break str
113+
else str s
114+
in
115+
hovbox_if wrap 1 (str "[" $ s $ str "]")
109116

110117
let fmt_math_span s = hovbox 2 (wrap (str "{m ") (str "}") (str s))
111118

@@ -163,8 +170,8 @@ let list_block_elem c elems f =
163170
(elem.Loc.value :> block_element)
164171
(n.value :> block_element)
165172
|| should_preserve_blank c elem.location n.location
166-
then str "\n" $ force_newline
167-
else force_newline
173+
then str "\n" $ force_break
174+
else force_break
168175
| None -> noop
169176
in
170177
f elem $ break )
@@ -231,7 +238,7 @@ let rec fmt_inline_elements c ~wrap elements =
231238
| `Word w :: t ->
232239
fmt_if (String.is_prefix ~prefix:"@" w) (str "\\")
233240
$ str_normalized ~wrap w $ aux t
234-
| `Code_span s :: t -> fmt_code_span s $ aux t
241+
| `Code_span s :: t -> fmt_code_span ~wrap s $ aux t
235242
| `Math_span s :: t -> fmt_math_span s $ aux t
236243
| `Raw_markup (lang, s) :: t ->
237244
let lang =
@@ -281,7 +288,8 @@ and fmt_markup_with_inline_elements c ~wrap ?(force_space = false) tag elems
281288
in
282289
str "{" $ tag $ leading_space $ fmt_inline_elements c ~wrap elems $ str "}"
283290

284-
and fmt_nestable_block_element c elm =
291+
and fmt_nestable_block_element c (elm : nestable_block_element with_location)
292+
=
285293
match elm.Loc.value with
286294
| `Paragraph elems ->
287295
hovbox 0
@@ -299,6 +307,20 @@ and fmt_nestable_block_element c elm =
299307
fmt_list_heavy c k items
300308
| `List (k, _syntax, items) -> fmt_list_light c k items
301309
| `Table table -> fmt_table c table
310+
| `Media (_kind, href, text, media) -> (
311+
let prefix =
312+
match media with
313+
| `Image -> "image"
314+
| `Video -> "video"
315+
| `Audio -> "audio"
316+
in
317+
let href =
318+
match href.value with
319+
| `Reference s -> str "!" $ str s
320+
| `Link s -> str ":" $ str s
321+
in
322+
let ref = str "{" $ str prefix $ href $ str "}" in
323+
match text with "" -> ref | _ -> str "{" $ ref $ str text $ str "}" )
302324

303325
and fmt_list_heavy c kind items =
304326
let fmt_item elems =
@@ -437,7 +459,7 @@ let wrap_see = function
437459
| `File -> wrap (str "'") (str "'")
438460
| `Document -> wrap (str "\"") (str "\"")
439461

440-
let fmt_tag c = function
462+
let fmt_tag c : tag -> _ = function
441463
| `Author s -> fmt_tag_args c "author" ~arg:(str s)
442464
| `Version s -> fmt_tag_args c "version" ~arg:(str s)
443465
| `See (k, sr, txt) -> fmt_tag_args c "see" ~arg:(wrap_see k (str sr)) ~txt
@@ -452,6 +474,8 @@ let fmt_tag c = function
452474
| `Closed -> fmt_tag_args c "closed"
453475
| `Hidden -> fmt_tag_args c "hidden"
454476
| `Canonical ref -> fmt_tag_args c "canonical" ~arg:(fmt_reference ref)
477+
| `Children_order txt -> fmt_tag_args c "children_order" ~txt
478+
| `Short_title txt -> fmt_tag_args c "short_title" ~txt
455479

456480
let fmt_block_element c elm =
457481
match elm.Loc.value with

Diff for: ‎test/passing/refs.default/doc_comments-no-wrap.mli.err

-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ Warning: doc_comments-no-wrap.mli:110 exceeds the margin
77
Warning: doc_comments-no-wrap.mli:115 exceeds the margin
88
Warning: doc_comments-no-wrap.mli:124 exceeds the margin
99
Warning: doc_comments-no-wrap.mli:328 exceeds the margin
10-
Warning: doc_comments-no-wrap.mli:384 exceeds the margin
1110
Warning: doc_comments-no-wrap.mli:556 exceeds the margin
1211
Warning: doc_comments-no-wrap.mli:625 exceeds the margin
1312
Warning: doc_comments-no-wrap.mli:648 exceeds the margin

Diff for: ‎test/passing/refs.default/doc_comments-no-wrap.mli.ref

+3-3
Original file line numberDiff line numberDiff line change
@@ -377,12 +377,12 @@ end
377377

378378
(** {%html:<p>Raw markup</p>%} {%Without language%} {%other:Other language%} *)
379379

380-
(** [Multi
381-
Line]
380+
(** [Multi Line]
382381

383382
[ A lot of spaces ]
384383

385-
[Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]
384+
[Very
385+
looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]
386386
*)
387387

388388
(** {[

Diff for: ‎test/passing/refs.default/doc_comments.mli.err

-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ Warning: doc_comments.mli:110 exceeds the margin
77
Warning: doc_comments.mli:115 exceeds the margin
88
Warning: doc_comments.mli:124 exceeds the margin
99
Warning: doc_comments.mli:328 exceeds the margin
10-
Warning: doc_comments.mli:384 exceeds the margin
1110
Warning: doc_comments.mli:556 exceeds the margin
1211
Warning: doc_comments.mli:625 exceeds the margin
1312
Warning: doc_comments.mli:648 exceeds the margin

Diff for: ‎test/passing/refs.default/doc_comments.mli.ref

+3-3
Original file line numberDiff line numberDiff line change
@@ -377,12 +377,12 @@ end
377377

378378
(** {%html:<p>Raw markup</p>%} {%Without language%} {%other:Other language%} *)
379379

380-
(** [Multi
381-
Line]
380+
(** [Multi Line]
382381

383382
[ A lot of spaces ]
384383

385-
[Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]
384+
[Very
385+
looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]
386386
*)
387387

388388
(** {[

Diff for: ‎test/passing/refs.default/js_source.ml.err

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@ Warning: js_source.ml:122 exceeds the margin
22
Warning: js_source.ml:156 exceeds the margin
33
Warning: js_source.ml:229 exceeds the margin
44
Warning: js_source.ml:327 exceeds the margin
5-
Warning: js_source.ml:809 exceeds the margin
5+
Warning: js_source.ml:808 exceeds the margin

Diff for: ‎test/passing/refs.default/js_source.ml.ref

+1-2
Original file line numberDiff line numberDiff line change
@@ -750,8 +750,7 @@ let _ =
750750

751751
(*$ (* *) *)
752752

753-
(** xxxxxxxxxxxxxxxxxxxxxxxxxxx [xxxxxxx
754-
xxxx]
753+
(** xxxxxxxxxxxxxxxxxxxxxxxxxxx [xxxxxxx xxxx]
755754
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx [xxxxxxx] *)
756755

757756
(* Hand-aligned comment

Diff for: ‎test/passing/refs.default/odoc.mli.ref

+51-2
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,56 @@
245245
@open
246246
@closed
247247
@hidden
248-
@canonical ref *)
248+
@canonical ref
249+
250+
@author Foo
251+
252+
{2 Bar}
253+
254+
@author Foo
255+
256+
- bar
257+
258+
@hidden
259+
260+
foo
261+
@hidden
262+
263+
@deprecated
264+
- foo
265+
- bar
266+
267+
@deprecated
268+
- foo
269+
- bar
270+
271+
@deprecated
272+
273+
{2 Bar}
274+
275+
@children_order
276+
foo
277+
- bar baz *)
249278

250279
(** {!foo} bar{!foo} {!foo}bar {!val:foo} {!} {!( * )} {!:foo} {!val:}
251-
{!"my-name"} {!"}"} {!( } )} {{!foo} bar} {{!foo} {b bar}} *)
280+
{!"my-name"} {!"}"} {!( } )} {{!foo} bar} {{!foo} {b bar}}
281+
282+
{image!foo}
283+
{audio!foo}
284+
{video!foo}
285+
{image:foo}
286+
{audio:foo}
287+
{video:foo}
288+
{{image!foo}bar}
289+
{{audio!foo}bar}
290+
{{video!foo}bar}
291+
{{image:foo}bar}
292+
{{audio:foo}bar}
293+
{{video:foo}bar} *)
294+
295+
(** fooooooooooooooo fooooooooooooooo fooooooooooooooo
296+
[fooooooooooooooo fooooooooooooooo] fooooooooooooooo
297+
298+
fooooooooooooooo
299+
[fooooooooooooooo fooooooooooooooo fooooooooooooooo fooooooooooooooo
300+
fooooooooooooooo fooooooooooooooo] fooooooooooooooo *)

Diff for: ‎test/passing/refs.janestreet/odoc.mli.err

+2
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
Warning: odoc.mli:130 exceeds the margin
2+
Warning: odoc.mli:306 exceeds the margin
3+
Warning: odoc.mli:308 exceeds the margin

Diff for: ‎test/passing/refs.janestreet/odoc.mli.ref

+50-2
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,37 @@
245245
@open
246246
@closed
247247
@hidden
248-
@canonical ref *)
248+
@canonical ref
249+
250+
@author Foo
251+
252+
{2 Bar}
253+
254+
@author Foo
255+
256+
- bar
257+
258+
@hidden
259+
260+
foo
261+
@hidden
262+
263+
@deprecated
264+
- foo
265+
- bar
266+
267+
@deprecated
268+
- foo
269+
- bar
270+
271+
@deprecated
272+
273+
{2 Bar}
274+
275+
@children_order
276+
foo
277+
- bar
278+
baz *)
249279

250280
(** {!foo}
251281
bar{!foo}
@@ -259,4 +289,22 @@
259289
{!"}"}
260290
{!( } )}
261291
{{!foo} bar}
262-
{{!foo} {b bar}} *)
292+
{{!foo} {b bar}}
293+
294+
{image!foo}
295+
{audio!foo}
296+
{video!foo}
297+
{image:foo}
298+
{audio:foo}
299+
{video:foo}
300+
{{image!foo}bar}
301+
{{audio!foo}bar}
302+
{{video!foo}bar}
303+
{{image:foo}bar}
304+
{{audio:foo}bar}
305+
{{video:foo}bar} *)
306+
307+
(** fooooooooooooooo fooooooooooooooo fooooooooooooooo [fooooooooooooooo fooooooooooooooo] fooooooooooooooo
308+
309+
fooooooooooooooo [fooooooooooooooo fooooooooooooooo fooooooooooooooo fooooooooooooooo fooooooooooooooo fooooooooooooooo] fooooooooooooooo
310+
*)

0 commit comments

Comments
 (0)