files_comments: add comments, slightly simplify the interface

4 files changed, 56 insertions, 11 deletions

diff --git a/src/file_comments.adb b/src/file_comments.adb
index d984d7d04..361a67437 100644
--- a/src/file_comments.adb
+++ b/src/file_comments.adb
@@ -112,6 +112,7 @@ package body File_Comments is
             Ctxt.State := State_Before;
          when State_Line_Cont =>
             --  If the line is empty, change to State_Block.
+            --  Otherwise, continue to associate with the last node.
             if Is_Empty_Line (Line_Start) then
                Ctxt.State := State_Block;
             end if;
@@ -151,7 +152,6 @@ package body File_Comments is
                Put ("block");
             end if;
          when State_Line =>
-            --  Is it on the same line ?
             if Flag_Trace then
                Put ("line");
                Put (" (start=");
@@ -160,10 +160,13 @@ package body File_Comments is
                Put_Uns32 (Uns32 (Line_Start));
                Put (")");
             end if;
+            --  Is it on the same line ?
             if Line_Start = Ctxt.Line_Start then
+               --  Yes, associate with the last node.
                N := Ctxt.Last_Node;
                Ctxt.Next := File_Comments_Tables.Last
                  (Comments_Table.Table (Ctxt.File)) + 2;
+               --  And continue to associate.
                Ctxt.State := State_Line_Cont;
             else
                --  Not the same line, for the next node.
@@ -171,7 +174,7 @@ package body File_Comments is
                Ctxt.State := State_Before;
             end if;
          when State_Line_Cont =>
-            --  Attached on the next empty line.
+            --  Continue to associate with the last node.
             if Flag_Trace then
                Put ("line_cont");
             end if;
@@ -239,11 +242,16 @@ package body File_Comments is
       Ctxt.Last_Node := N;
    end Gather_Comments_Block;
 
-   procedure Gather_Comments_Line (Rng : Comments_Range;
-                                   Pos : Source_Ptr;
-                                   N : Uns32) is
+   procedure Gather_Comments_Line (Pos : Source_Ptr;
+                                   N : Uns32)
+   is
+      Rng : Comments_Range;
    begin
+      --  Previous unassociated comments are associated to the node N.
+      Save_Comments (Rng);
       Gather_Comments_Before (Rng, N);
+
+      --  Start Line mode.
       Ctxt.State := State_Line;
       Ctxt.Last_Node := N;
       Ctxt.Line_Start := Pos;
diff --git a/src/file_comments.ads b/src/file_comments.ads
index 8bb4d117d..715116966 100644
--- a/src/file_comments.ads
+++ b/src/file_comments.ads
@@ -19,6 +19,44 @@ with Dyn_Tables;
 with Tables;
 
 package File_Comments is
+   --  Usage of File_Comments:
+   --  There are two parts: the generating part which gather comments and
+   --  associate them to nodes, and the user part which allow to get comments
+   --  for a node.
+   --
+   --  The generating part is combined work done by the scanner and the
+   --  parser.  The scanner calls Add_Comment on evey comment, and
+   --  Comment_Newline on every newlines after a comment.
+   --  The parser does the remaining work: it initializes and finishes the
+   --  process (calls Comment_Init_Scan and Comment_Close_Scan).
+   --  It also associate comments with nodes.
+   --
+   --  There are two modes of association: block and line.
+   --
+   --  Line is the simplest mode: it starts by calling Gather_Comments_Line.
+   --  First, it associates previous comments to the node, and then if a
+   --  comment appear on the same line as the node, all consecutive comments
+   --  are associated with the node.  Consecutive comments mean comments
+   --  without empty lines.  Another declaration or statement will also
+   --  interrupt this association because the comments will be associated
+   --  with this new declaration or statement.  After interruption, comments
+   --  are not associated anymore; they will be associated by the next
+   --  call.  Finally, Gather_Comments_End will simply discard unassociated
+   --  comments that appears at an end (or before an 'end').
+   --
+   --  Block is the default mode.  Gathered but unassociated comments are
+   --  simply associated with a node.  The following comments are also
+   --  associated with the current node only when an empty line appears.
+   --  The block mode is made more complex by the possibility of saving
+   --  a range of comments because parsing and scanning needs to be
+   --  continued before building a node (eg: to distinguish package
+   --  declaration and package instantiation, or to distinguish process and
+   --  sensitized process).
+   --
+   --  Before use, Sort_Comments_By_Node must be called to sort comments.
+   --  Then the iterator can be called to get the comments associated to a
+   --  node.
+
    --  To be called at begin/end of scan to initialize the context.
    --  TODO: nested context ?
    procedure Comment_Init_Scan (File : Source_File_Entry);
@@ -50,8 +88,7 @@ package File_Comments is
    --  annotated with a comment is parsed.
    procedure Gather_Comments_Block (Rng : Comments_Range;
                                     N : Uns32);
-   procedure Gather_Comments_Line (Rng : Comments_Range;
-                                   Pos : Source_Ptr;
+   procedure Gather_Comments_Line (Pos : Source_Ptr;
                                    N : Uns32);
 
    --  Assign node N to the last comments scanned.
diff --git a/src/vhdl/vhdl-comments.adb b/src/vhdl/vhdl-comments.adb
index d8c64610e..16587c843 100644
--- a/src/vhdl/vhdl-comments.adb
+++ b/src/vhdl/vhdl-comments.adb
@@ -37,11 +37,9 @@ package body Vhdl.Comments is
    procedure Gather_Comments_Line (N : Iir)
    is
       Coord : Source_Coord_Type;
-      Rng : Comments_Range;
    begin
-      Save_Comments (Rng);
       Coord := Scanner.Get_Current_Coord;
-      Gather_Comments_Line (Rng, Coord.Line_Pos, Uns32 (N));
+      Gather_Comments_Line (Coord.Line_Pos, Uns32 (N));
    end Gather_Comments_Line;
 
    function Find_First_Comment (File : Source_File_Entry; N : Node)
diff --git a/src/vhdl/vhdl-parse.adb b/src/vhdl/vhdl-parse.adb
index 421a08edc..044f74e79 100644
--- a/src/vhdl/vhdl-parse.adb
+++ b/src/vhdl/vhdl-parse.adb
@@ -11196,7 +11196,7 @@ package body Vhdl.Parse is
       return Res;
    end Parse_Package_Header;
 
-   --  precond : token (after 'IS')
+   --  precond : token (after 'IS', the first token of declarations or header).
    --  postcond: next token.
    --
    --  [ LRM93 2.5, LRM08 4.7 ]
@@ -11396,6 +11396,8 @@ package body Vhdl.Parse is
          end if;
 
          if Flag_Gather_Comments then
+            --  Save existing comments (before the 'is').  Those comments will
+            --  be associated with this package.
             File_Comments.Save_Comments (Comments);
          end if;