From 78760e12065e49d5b11d3edf0eb397866ac1ebfa Mon Sep 17 00:00:00 2001 From: Tristan Gingold Date: Tue, 20 Dec 2022 06:56:36 +0100 Subject: files_comments: add comments, slightly simplify the interface --- src/file_comments.adb | 18 +++++++++++++----- src/file_comments.ads | 41 +++++++++++++++++++++++++++++++++++++++-- src/vhdl/vhdl-comments.adb | 4 +--- src/vhdl/vhdl-parse.adb | 4 +++- 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; -- cgit v1.2.3