Frontmatter: Warn when a tag is not before any content

Author: panglesd

src/model/semantics.ml

@@ -543,21 +543,28 @@ let top_level_block_elements status ast_elements =
   traverse ~top_heading_level [] ast_elements
 
 let strip_internal_tags ast : internal_tags_removed with_location list * _ =
-  let rec loop tags ast' = function
+  let rec loop ~start tags ast' = function
     | ({ Location.value = `Tag (#Ast.internal_tag as tag); _ } as wloc) :: tl
       -> (
-        let next tag = loop ({ wloc with value = tag } :: tags) ast' tl in
+        let next tag =
+          loop ~start ({ wloc with value = tag } :: tags) ast' tl
+        in
         match tag with
         | (`Inline | `Open | `Closed | `Hidden) as tag -> next tag
-        | `Children_order co -> next (`Children_order co)
+        | `Children_order co ->
+            if not start then
+              Error.raise_warning
+                (Error.make "@children_order tag has to be before any content"
+                   wloc.location);
+            next (`Children_order co)
         | `Canonical { Location.value = s; location = r_location } -> (
             match
               Error.raise_warnings (Reference.read_path_longident r_location s)
             with
             | Result.Ok path -> next (`Canonical path)
             | Result.Error e ->
                 Error.raise_warning e;
-                loop tags ast' tl))
+                loop ~start tags ast' tl))
     | ({
          value =
            ( `Tag #Ast.ocamldoc_tag
@@ -566,10 +573,10 @@ let strip_internal_tags ast : internal_tags_removed with_location list * _ =
          _;
        } as hd)
       :: tl ->
-        loop tags (hd :: ast') tl
+        loop ~start:false tags (hd :: ast') tl
     | [] -> (List.rev ast', List.rev tags)
   in
-  loop [] [] ast
+  loop ~start:true [] [] ast
 
 (** Append alerts at the end of the comment. Tags are favoured in case of alerts of the same name. *)
 let append_alerts_to_comment alerts

test/frontmatter/frontmatter.t/one_frontmatter.mld

@@ -1,3 +1,3 @@
-{0 One frontmatter}
+@children_order page1 page2
 
-@children_order page1 page2
+{0 One frontmatter}

test/frontmatter/frontmatter.t/run.t

@@ -59,7 +59,7 @@ When there is one frontmatter, it is extracted from the content:
 When there is more than one children order, we raise a warning and keep only the first entry:
 
   $ odoc compile two_frontmatters.mld
-  File "two_frontmatters.mld", line 5, characters 0-25:
+  File "two_frontmatters.mld", line 2, characters 0-25:
   Warning: Duplicated @children_order entry
   File "two_frontmatters.mld":
   Warning: Non-index page cannot specify (children _) in the frontmatter.

test/frontmatter/frontmatter.t/two_frontmatters.mld

@@ -1,5 +1,4 @@
-{0 Two frontmatters}
-
 @children_order bli1 bli2
+@children_order bli3 bli4
 
-@children_order bli3 bli4
+{0 Two frontmatters}

test/frontmatter/toc_order.t/index.mld

@@ -1,5 +1,5 @@
+@children_order content dir1/ dir1/ typo
+
 {0 This is the main index}
 
 Hello
-
-@children_order content dir1/ dir1/ typo

test/frontmatter/toc_order.t/run.t

@@ -13,11 +13,11 @@
   $ odoc link _odoc/pkg/dir1/page-dontent.odoc
 
   $ odoc compile-index -P test:_odoc/pkg
-  File "index.mld", line 5, characters 30-35:
+  File "index.mld", line 1, characters 30-35:
   Warning: Duplicate 'dir1/' in (children).
-  File "index.mld", line 5, characters 36-40:
+  File "index.mld", line 1, characters 36-40:
   Warning: 'typo' in (children) does not correspond to anything.
-  File "index.mld", line 5, characters 0-40:
+  File "index.mld", line 1, characters 0-40:
   Warning: (children) doesn't include 'omitted'.
 
   $ odoc html-generate --indent --index index.odoc-index -o _html  _odoc/pkg/page-index.odocl
@@ -76,17 +76,33 @@ Some more parsing test:
 
   $ mkdir errors
   $ cat << EOF >> errors/index.mld
-  > {0 Test1}
   > @children_order [Some wrong content]
+  > {0 Test1}
   > EOF
   $ odoc compile --parent-id pkg/doc --output-dir _odoc errors/index.mld
-  File "errors/index.mld", line 2, characters 16-36:
+  File "errors/index.mld", line 1, characters 16-36:
   Warning: Only words are accepted when specifying children order
 
   $ mkdir valid
   $ cat << EOF > valid/index.mld
-  > {0 Test1}
   > @children_order a
   >            b                     c
+  > {0 Test1}
   > EOF
   $ odoc compile --parent-id pkg/doc --output-dir _odoc valid/index.mld
+
+  $ cat << EOF > errors/index.mld
+  > {0 Test1}
+  > @children_order a
+  > EOF
+  $ odoc compile --parent-id pkg/doc --output-dir _odoc errors/index.mld
+  File "errors/index.mld", line 2, characters 0-17:
+  Warning: @children_order tag has to be before any content
+
+  $ cat << EOF > errors/not_index.mld
+  > @children_order a
+  > {0 Test1}
+  > EOF
+  $ odoc compile --parent-id pkg/doc --output-dir _odoc errors/not_index.mld
+  File "errors/not_index.mld":
+  Warning: Non-index page cannot specify (children _) in the frontmatter.