From e80e5ca6bac656d08f50141bf208345610ea5200 Mon Sep 17 00:00:00 2001
From: Torben Ewert <torben@ewert-online.com>
Date: Sun, 05 Apr 2026 09:49:38 +0000
Subject: [PATCH] feat: allow comments above declarations

---
 lib/02_parsing/Lexer.ml | 2 ++
 lib/02_parsing/Parser.ml | 20 ++++++++++++++++++--
 lib/02_parsing/Parsetree.ml | 7 ++++++-
 lib/pinc_format/Formatter.ml | 14 +++++++++++---
 test/format/data.pi | 1 +
 test/format/run.t | 3 +++
 6 file(s) changed, 41 insertion(s)(+), 6 deletion(s)(-)

diff --git a/lib/02_parsing/Lexer.ml b/lib/02_parsing/Lexer.ml
--- a/lib/02_parsing/Lexer.ml
+++ b/lib/02_parsing/Lexer.ml
@@ -683,6 +683,8 @@
 ;;
 
 let scan_comment t =
+  eat2 t;
+  skip_whitespace t;
   let rec loop buf t =
     match t.current with
     (* This case also matches \r\n on windows *)
diff --git a/lib/02_parsing/Parser.ml b/lib/02_parsing/Parser.ml
--- a/lib/02_parsing/Parser.ml
+++ b/lib/02_parsing/Parser.ml
@@ -158,7 +158,16 @@
 end
 
 module Rules = struct
-  let rec parse_string_template t =
+  let rec parse_annotations t = Helpers.list ~fn:parse_annotation t
+
+  and parse_annotation t =
+    match t.token.typ with
+    | Token.COMMENT s ->
+        next t;
+        Some (Parsetree.P_Comment_Annotation s)
+    | _ -> None
+
+  and parse_string_template t =
     let string_template_start = t.token.location in
     let* string_template_desc =
       match t.token.typ with
@@ -815,6 +824,7 @@
     Some (loop ~prio ~left t)
 
   and parse_declaration t =
+    let declaration_annotations = parse_annotations t in
     let declaration_start = t.token.location in
     let* declaration_kind =
       match t.token.typ with
@@ -857,7 +867,13 @@
     let declaration_loc = Location.merge ~s:declaration_start ~e:declaration_end () in
     ( identifier,
       Parsetree.
-        { declaration_loc; declaration_kind; declaration_attributes; declaration_body } )
+        {
+          declaration_loc;
+          declaration_kind;
+          declaration_attributes;
+          declaration_body;
+          declaration_annotations;
+        } )
     |> Option.some
   ;;
 end
diff --git a/lib/02_parsing/Parsetree.ml b/lib/02_parsing/Parsetree.ml
--- a/lib/02_parsing/Parsetree.ml
+++ b/lib/02_parsing/Parsetree.ml
@@ -1,6 +1,10 @@
 module Operators = Operators
 
-type uppercase_identifier = P_Uppercase_Id of (string * Pinc_Diagnostics.Location.t)
+type annotation =
+  | P_Comment_Annotation of string
+  | P_Blankline_Annotation of int
+
+and uppercase_identifier = P_Uppercase_Id of (string * Pinc_Diagnostics.Location.t)
 and lowercase_identifier = P_Lowercase_Id of (string * Pinc_Diagnostics.Location.t)
 
 and template_node = {
@@ -128,6 +132,7 @@
   declaration_kind : declaration_kind;
   declaration_attributes : (string * expression) list;
   declaration_body : expression;
+  declaration_annotations : annotation list;
 }
 
 and declaration_kind =
diff --git a/lib/pinc_format/Formatter.ml b/lib/pinc_format/Formatter.ml
--- a/lib/pinc_format/Formatter.ml
+++ b/lib/pinc_format/Formatter.ml
@@ -29,14 +29,21 @@
   ;;
 end
 
-let rec format_lowercase_id = function
+let rec format_annotations annotations = concat_map format_annotation annotations
+
+and format_annotation = function
+  | Parsetree.P_Comment_Annotation s -> format_comment s ^^ hardline
+  | Parsetree.P_Blankline_Annotation i -> repeat i hardline
+
+and format_lowercase_id = function
   | Parsetree.P_Lowercase_Id (id, _loc) -> string id
 
 and format_uppercase_id = function
   | Parsetree.P_Uppercase_Id (id, _loc) -> string id
 
 and format_comment comment =
-  string "/*" ^^ space ^^ utf8string comment ^^ space ^^ string "*/"
+  let comment = nest 2 (ifflat empty (break 1) ^^ arbitrary_string comment) in
+  string "/*" ^^ group (comment ^^ ifflat empty (break 1)) ^^ string "*/"
 
 and format_string templates =
   let templates =
@@ -452,6 +459,7 @@
   | P_ExpressionStatement s -> format_expression_stmt s
 
 and format_declaration key (declaration : Parsetree.declaration) =
+  let annotations = format_annotations declaration.declaration_annotations in
   let typ =
     match declaration.declaration_kind with
     | P_Declaration_Component -> string "component"
@@ -465,7 +473,7 @@
       declaration.declaration_attributes
   in
   let body = format_expression declaration.declaration_body in
-  typ ^^ blank 1 ^^ string key ^^ parens attributes ^^ blank 1 ^^ body
+  annotations ^^ typ ^^ blank 1 ^^ string key ^^ parens attributes ^^ blank 1 ^^ body
 
 and format_declarations declarations =
   let declarations =
diff --git a/test/format/data.pi b/test/format/data.pi
--- a/test/format/data.pi
+++ b/test/format/data.pi
@@ -1,3 +1,4 @@
+// Some Comment Eiusmod eiusmod tempor eiusmod nostrud nostrud nostrud in nisi ipsum ullamco ipsum esse enim laborum cupidatat. Deserunt duis culpa consectetur est duis.
 page Docs(label: "Docs", icon: "/images/icons/page-docs.svg",) {
   use Math = Base.Math;
 
diff --git a/test/format/run.t b/test/format/run.t
--- a/test/format/run.t
+++ b/test/format/run.t
@@ -1,4 +1,7 @@
   $ pincfmt ./data.pi
+  /*
+    Some Comment Eiusmod eiusmod tempor eiusmod nostrud nostrud nostrud in nisi ipsum ullamco ipsum esse enim laborum cupidatat. Deserunt duis culpa consectetur est duis.
+  */
   page Docs(label: "Docs", icon: "/images/icons/page-docs.svg") {
     use Math = Base.Math;
     let fruits = ["apples", "oranges", "bannanas", "melons"];

--
tangled.sh