fixes

lib/check/datatype/dt_email.mli

···
 (** Valid email address validator.
 
     Validates a single email address. Uses simplified validation rules:
-    - Must contain exactly one '@' character
-    - Local part (before @) must be non-empty
-    - Domain part (after @) must be non-empty and contain at least one '.'
+    - Must contain exactly one ['@'] character
+    - Local part (before ['@']) must be non-empty
+    - Domain part (after ['@']) must be non-empty and contain at least one ['.']
     - Only ASCII characters allowed *)
 module Email : Datatype.S
 

lib/check/datatype/dt_media_query.mli

···
 
 (** Media query validator.
 
-    Validates CSS media queries used in media attributes and CSS @media rules.
+    Validates CSS media queries used in media attributes and CSS [@@media] rules.
 
     Examples:
     - "screen"

lib/check/element/element.mli

···
 
 (** A typed HTML element.
 
-    @field tag The element's tag classification
-    @field attrs Typed attributes parsed from raw input
-    @field raw_attrs Original attribute name-value pairs for fallback *)
+    - [tag]: The element's tag classification
+    - [attrs]: Typed attributes parsed from raw input
+    - [raw_attrs]: Original attribute name-value pairs for fallback *)
 type t = {
   tag : Tag.element_tag;
   attrs : Attr.t list;

lib/check/htmlrw_check.mli

···
 
     {2 Handling Specific Errors}
 
-    Use pattern matching on {!field-message.error_code} for fine-grained control:
+    Use pattern matching on [error_code] for fine-grained control:
 
     {[
       List.iter (fun msg ->
···
 
 (** Human-readable text format.
 
-    {v
+{v
 file.html:5.3: error [missing-alt]: Element "img" is missing required attribute "alt".
-    v} *)
+v} *)
 val to_text : t -> string
 
 (** JSON format compatible with Nu HTML Validator.
 
-    {v
+{v
 {"messages":[{"type":"error","message":"...","firstLine":5,"firstColumn":3}]}
-    v} *)
+v} *)
 val to_json : t -> string
 
 (** GNU error format for IDE integration.
 
-    {v
+{v
 file.html:5:3: error: Element "img" is missing required attribute "alt".
-    v} *)
+v} *)
 val to_gnu : t -> string
 
 

lib/check/specialized/title_checker.ml

···
 (** Title element validation checker. *)
 
 type state = {
+  mutable seen_html : bool;  (* true if we've seen html element (full document mode) *)
   mutable in_head : bool;
   mutable head_had_children : bool;  (* true if head contained any child elements *)
   mutable has_title : bool;
···
 }
 
 let create () = {
+  seen_html = false;
   in_head = false;
   head_had_children = false;
   has_title = false;
···
 }
 
 let reset state =
+  state.seen_html <- false;
   state.in_head <- false;
   state.head_had_children <- false;
   state.has_title <- false;
···
 
 let start_element state ~element _collector =
   (match element.Element.tag with
-   | Tag.Html `Html -> ()
+   | Tag.Html `Html ->
+     state.seen_html <- true
    | Tag.Html `Head ->
      state.in_head <- true;
      state.head_had_children <- false
···
         (`Element (`Must_not_be_empty (`Elem "title")));
     state.in_title <- false
   | Tag.Html `Head ->
-    (* Only report missing title if head had children (was explicit with content).
-       An empty head was likely implicit (fragment validation from body). *)
-    if state.in_head && not state.has_title && state.head_had_children then
+    (* Report missing title if:
+       - We saw an html element (full document mode), OR
+       - Head had explicit children (was not just an implicit empty head)
+       An empty head without html element was likely implicit (fragment validation). *)
+    if state.in_head && not state.has_title && (state.seen_html || state.head_had_children) then
       Message_collector.add_typed collector
         (`Element (`Missing_child (`Parent "head", `Child "title")));
     state.in_head <- false

lib/html5rw/parser/parser.mli

···
 (** Result of parsing an HTML document or fragment.
 
     This opaque type contains:
-    - The DOM tree (access via {!root})
-    - Parse errors if collection was enabled (access via {!errors})
-    - Detected encoding for byte input (access via {!encoding})
+    - The DOM tree (access via {!val:root})
+    - Parse errors if collection was enabled (access via {!val:errors})
+    - Detected encoding for byte input (access via {!val:encoding})
 *)
 type t
 
···
     3. {b Transport hint}: Use [transport_encoding] if provided
     4. {b Fallback}: Use UTF-8
 
-    The detected encoding is stored in the result (access via {!encoding}).
+    The detected encoding is stored in the result (access via {!val:encoding}).
 
     {b Prescan details:}
 

lib/js/htmlrw_js.mli

···
 (** Validate an HTML string.
 
     This is the simplest form of validation. Since there's no source element,
-    the returned {!browser_message}s will not have element references.
+    the returned messages will not have element references.
 
     {[
       let result = validate_string "<html><body><img></body></html>" in
···
     descendants are annotated with data attributes, classes, and optionally
     tooltips based on the validation results.
 
-    @param config Annotation configuration. Defaults to {!default_annotation_config}. *)
+    @param config Annotation configuration. Defaults to
+           [Htmlrw_js_types.default_annotation_config]. *)
 val validate_and_annotate :
   ?config:annotation_config -> Brr.El.t -> result