Skip to content

Commit af146db

Browse files
godunkogodunko
committed
Code refactoring.
Generalize code to extract leading section of the documentation.
1 parent 89a7b45 commit af146db

File tree

1 file changed

+116
-134
lines changed

1 file changed

+116
-134
lines changed

‎source/gnatdoc-comments-extractor.adb‎

Lines changed: 116 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -158,23 +158,6 @@ package body GNATdoc.Comments.Extractor is
158158
-- group comment is started.
159159
-- @param Documentation Structured comment to fill.
160160

161-
procedure Extract_General_Leading_Documentation
162-
(Decl_Node : Basic_Decl'Class;
163-
Pattern : VSS.Regular_Expressions.Regular_Expression;
164-
Documentation : in out Structured_Comment'Class;
165-
Leading_Section : out not null Section_Access);
166-
-- Creates leading documetation section of the structured comment
167-
-- and extracts leading documentation follow general rules (there are
168-
-- few exceptions from this rules, like ordinary and generic package
169-
-- declarations).
170-
--
171-
-- @param Decl_Node Declaration node
172-
-- @param Pattern
173-
-- Regular expression to check whenther line should be included into
174-
-- the documentation or not.
175-
-- @param Documentation Structured comment to add and fill section
176-
-- @param Leading_Section Created section
177-
178161
procedure Extract_General_Trailing_Documentation
179162
(Decl_Node : Basic_Decl'Class;
180163
Pattern : VSS.Regular_Expressions.Regular_Expression;
@@ -202,7 +185,7 @@ package body GNATdoc.Comments.Extractor is
202185

203186
procedure Extract_General_Leading_Trailing_Documentation
204187
(Decl_Node : Basic_Decl'Class;
205-
Pattern : VSS.Regular_Expressions.Regular_Expression;
188+
Options : GNATdoc.Comments.Options.Extractor_Options;
206189
Last_Section : Section_Access;
207190
Minimum_Indent : Langkit_Support.Slocs.Column_Number;
208191
Documentation : in out Structured_Comment'Class;
@@ -211,6 +194,24 @@ package body GNATdoc.Comments.Extractor is
211194
-- Call both Extract_General_Leading_Documentation and
212195
-- Extract_General_Trailing_Documentation subprograms.
213196

197+
procedure Extract_Leading_Section
198+
(Token_Start : Token_Reference;
199+
Options : GNATdoc.Comments.Options.Extractor_Options;
200+
Separator_Allowed : Boolean;
201+
Documentation : in out Structured_Comment'Class;
202+
Section : out not null Section_Access);
203+
-- Creates leading documetation section of the structured comment
204+
-- and extracts leading documentation.
205+
--
206+
-- @param Token_Start Start token of the declaration node.
207+
-- @param Options Extractor options
208+
-- @param Separator_Allowed
209+
-- Whether empty line is allowed between line that contains Token_Start
210+
-- and comment. It is the case for packages, tasks and protected
211+
-- objects.
212+
-- @param Documentation Structured comment to add and fill section
213+
-- @param Section Created section
214+
214215
procedure Extract_Upper_Intermediate_Section
215216
(Token_Start : Token_Reference;
216217
Token_End : Token_Reference;
@@ -516,15 +517,6 @@ package body GNATdoc.Comments.Extractor is
516517
Last_Pragma_Or_Use : Ada_Node;
517518

518519
begin
519-
Leading_Section :=
520-
new Section'
521-
(Kind => Raw,
522-
Symbol => "<<LEADING>>",
523-
Name => <>,
524-
Text => <>,
525-
others => <>);
526-
Documentation.Sections.Append (Leading_Section);
527-
528520
-- Header section: before context clauses of compilation unit
529521

530522
if Basic_Decl_Node.P_Is_Compilation_Unit_Root then
@@ -596,49 +588,12 @@ package body GNATdoc.Comments.Extractor is
596588
-- clauses of the compilation unit
597589

598590
if not Basic_Decl_Node.P_Is_Compilation_Unit_Root or Prelude.Is_Null then
599-
declare
600-
Token : Token_Reference := Basic_Decl_Node.Token_Start;
601-
Found : Boolean := False;
602-
603-
begin
604-
loop
605-
Token := Previous (Token);
606-
607-
exit when Token = No_Token;
608-
609-
case Kind (Data (Token)) is
610-
when Ada_Comment =>
611-
if Found then
612-
Prepend_Documentation_Line
613-
(Leading_Section.Text,
614-
Text (Token),
615-
Options.Pattern);
616-
end if;
617-
618-
when Ada_Whitespace =>
619-
declare
620-
Location : constant Source_Location_Range :=
621-
Sloc_Range (Data (Token));
622-
623-
begin
624-
if Location.End_Line - Location.Start_Line > 1 then
625-
exit when Found;
626-
627-
Found := True;
628-
end if;
629-
end;
630-
631-
when others =>
632-
-- Leading section must be separated from the context
633-
-- clauses by the empty line, thus any other tokens
634-
-- cleanup accumulated text.
635-
636-
Leading_Section.Text.Clear;
637-
638-
exit;
639-
end case;
640-
end loop;
641-
end;
591+
Extract_Leading_Section
592+
(Basic_Decl_Node.Token_Start,
593+
Options,
594+
True,
595+
Documentation,
596+
Leading_Section);
642597
end if;
643598

644599
-- Looukp last use clause or pragma declarations at the beginning of the
@@ -743,7 +698,9 @@ package body GNATdoc.Comments.Extractor is
743698
then
744699
Raw_Section := Intermediate_Lower_Section;
745700

746-
elsif not Leading_Section.Text.Is_Empty then
701+
elsif Leading_Section /= null
702+
and then not Leading_Section.Text.Is_Empty
703+
then
747704
Raw_Section := Leading_Section;
748705

749706
elsif Header_Section /= null
@@ -797,7 +754,7 @@ package body GNATdoc.Comments.Extractor is
797754

798755
Extract_General_Leading_Trailing_Documentation
799756
(Decl_Node => Node,
800-
Pattern => Options.Pattern,
757+
Options => Options,
801758
Last_Section => Last_Section,
802759
Minimum_Indent => Minimum_Indent,
803760
Documentation => Documentation,
@@ -844,77 +801,28 @@ package body GNATdoc.Comments.Extractor is
844801
end;
845802
end Extract_Enumeration_Type_Documentation;
846803

847-
-------------------------------------------
848-
-- Extract_General_Leading_Documentation --
849-
-------------------------------------------
850-
851-
procedure Extract_General_Leading_Documentation
852-
(Decl_Node : Basic_Decl'Class;
853-
Pattern : VSS.Regular_Expressions.Regular_Expression;
854-
Documentation : in out Structured_Comment'Class;
855-
Leading_Section : out not null Section_Access) is
856-
begin
857-
-- Create and add leading section
858-
859-
Leading_Section :=
860-
new Section'
861-
(Kind => Raw,
862-
Symbol => "<<LEADING>>",
863-
Name => <>,
864-
Text => <>,
865-
others => <>);
866-
Documentation.Sections.Append (Leading_Section);
867-
868-
-- Process tokens before the declaration node.
869-
870-
declare
871-
Token : Token_Reference := Decl_Node.Token_Start;
872-
873-
begin
874-
loop
875-
Token := Previous (Token);
876-
877-
exit when Token = No_Token;
878-
879-
case Kind (Data (Token)) is
880-
when Ada_Comment =>
881-
Prepend_Documentation_Line
882-
(Leading_Section.Text, Text (Token), Pattern);
883-
884-
when Ada_Whitespace =>
885-
declare
886-
Location : constant Source_Location_Range :=
887-
Sloc_Range (Data (Token));
888-
889-
begin
890-
exit when Location.End_Line - Location.Start_Line > 1;
891-
end;
892-
893-
when others =>
894-
exit;
895-
end case;
896-
end loop;
897-
end;
898-
end Extract_General_Leading_Documentation;
899-
900804
----------------------------------------------------
901805
-- Extract_General_Leading_Trailing_Documentation --
902806
----------------------------------------------------
903807

904808
procedure Extract_General_Leading_Trailing_Documentation
905809
(Decl_Node : Basic_Decl'Class;
906-
Pattern : VSS.Regular_Expressions.Regular_Expression;
810+
Options : GNATdoc.Comments.Options.Extractor_Options;
907811
Last_Section : Section_Access;
908812
Minimum_Indent : Langkit_Support.Slocs.Column_Number;
909813
Documentation : in out Structured_Comment'Class;
910814
Leading_Section : out not null Section_Access;
911815
Trailing_Section : out not null Section_Access) is
912816
begin
913-
Extract_General_Leading_Documentation
914-
(Decl_Node, Pattern, Documentation, Leading_Section);
817+
Extract_Leading_Section
818+
(Decl_Node.Token_Start,
819+
Options,
820+
False,
821+
Documentation,
822+
Leading_Section);
915823
Extract_General_Trailing_Documentation
916824
(Decl_Node,
917-
Pattern,
825+
Options.Pattern,
918826
Last_Section,
919827
Minimum_Indent,
920828
Documentation,
@@ -1044,6 +952,80 @@ package body GNATdoc.Comments.Extractor is
1044952
(Node, Node.F_Package_Decl, Options, Documentation);
1045953
end Extract_Generic_Package_Decl_Documentation;
1046954

955+
-----------------------------
956+
-- Extract_Leading_Section --
957+
-----------------------------
958+
959+
procedure Extract_Leading_Section
960+
(Token_Start : Token_Reference;
961+
Options : GNATdoc.Comments.Options.Extractor_Options;
962+
Separator_Allowed : Boolean;
963+
Documentation : in out Structured_Comment'Class;
964+
Section : out not null Section_Access) is
965+
begin
966+
-- Create and add leading section
967+
968+
Section :=
969+
new GNATdoc.Comments.Section'
970+
(Kind => Raw,
971+
Symbol => "<<LEADING>>",
972+
Name => <>,
973+
Text => <>,
974+
others => <>);
975+
Documentation.Sections.Append (Section);
976+
977+
-- Process tokens before the start token.
978+
979+
declare
980+
Token : Token_Reference := Token_Start;
981+
Found : Boolean := False;
982+
-- Separated : Boolean := False;
983+
984+
begin
985+
loop
986+
Token := Previous (Token);
987+
988+
exit when Token = No_Token;
989+
990+
case Kind (Data (Token)) is
991+
when Ada_Comment =>
992+
Found := True;
993+
Prepend_Documentation_Line
994+
(Section.Text, Text (Token), Options.Pattern);
995+
996+
when Ada_Whitespace =>
997+
declare
998+
Location : constant Source_Location_Range :=
999+
Sloc_Range (Data (Token));
1000+
1001+
begin
1002+
if Location.End_Line - Location.Start_Line > 1 then
1003+
if not Separator_Allowed then
1004+
exit;
1005+
1006+
else
1007+
exit when Found;
1008+
1009+
Found := True;
1010+
end if;
1011+
end if;
1012+
end;
1013+
1014+
when others =>
1015+
-- Leading section must be separated from the context
1016+
-- clauses by the empty line, thus any other tokens
1017+
-- cleanup accumulated text.
1018+
1019+
if Separator_Allowed then
1020+
Section.Text.Clear;
1021+
end if;
1022+
1023+
exit;
1024+
end case;
1025+
end loop;
1026+
end;
1027+
end Extract_Leading_Section;
1028+
10471029
---------------------------------------
10481030
-- Extract_Record_Type_Documentation --
10491031
---------------------------------------
@@ -1078,7 +1060,7 @@ package body GNATdoc.Comments.Extractor is
10781060

10791061
Extract_General_Leading_Trailing_Documentation
10801062
(Decl_Node => Node,
1081-
Pattern => Options.Pattern,
1063+
Options => Options,
10821064
Last_Section => Last_Section,
10831065
Minimum_Indent => Minimum_Indent,
10841066
Documentation => Documentation,
@@ -1146,7 +1128,7 @@ package body GNATdoc.Comments.Extractor is
11461128

11471129
Extract_General_Leading_Trailing_Documentation
11481130
(Decl_Node => Node,
1149-
Pattern => Options.Pattern,
1131+
Options => Options,
11501132
Last_Section => null,
11511133
Minimum_Indent => 0,
11521134
Documentation => Documentation,
@@ -1209,8 +1191,8 @@ package body GNATdoc.Comments.Extractor is
12091191
Intermediate_Upper_Section : Section_Access;
12101192

12111193
begin
1212-
Extract_General_Leading_Documentation
1213-
(Node, Options.Pattern, Documentation, Leading_Section);
1194+
Extract_Leading_Section
1195+
(Node.Token_Start, Options, True, Documentation, Leading_Section);
12141196

12151197
if Definition.Is_Null then
12161198
-- It is the case of the entry-less and definition-less task
@@ -1478,7 +1460,7 @@ package body GNATdoc.Comments.Extractor is
14781460

14791461
Extract_General_Leading_Trailing_Documentation
14801462
(Decl_Node => Decl_Node,
1481-
Pattern => Options.Pattern,
1463+
Options => Options,
14821464
Last_Section => Last_Section,
14831465
Minimum_Indent => Minimum_Indent,
14841466
Documentation => Documentation,

0 commit comments

Comments
 (0)