Skip to content

Commit 2fed9e0

Browse files
fingolfinfingolfin
committed
Ignore commented out declarations
1 parent 5d35e72 commit 2fed9e0

4 files changed

Lines changed: 58 additions & 28 deletions

File tree

‎gap/Parser.gi‎

Lines changed: 35 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,27 @@
55
#
66
# SPDX-License-Identifier: GPL-2.0-or-later
77

8+
## Check if the string <line> starts with whitespaces followed by <prefix>; if
9+
## this is the case, returns the start position of <prefix>, otherwise fail.
10+
BindGlobal( "AUTODOC_PositionWhitespacePrefix",
11+
function( line, prefix )
12+
local position;
13+
# ignore leading whitespace
14+
position := PositionProperty( line, x -> not x in " \t" );
15+
if position = fail or position+Length(prefix)-1 > Length(line) then
16+
return fail;
17+
fi;
18+
if line{[position..position+Length(prefix)-1]} = prefix then
19+
return position;
20+
fi;
21+
return fail;
22+
end );
23+
824
##
925
InstallGlobalFunction( Scan_for_AutoDoc_Part,
1026
function( line, plain_text_mode )
1127
local position, whitespace_position, command, argument;
12-
#! @DONT_SCAN_NEXT_LINE
13-
position := PositionSublist( line, "#!" );
28+
position := AUTODOC_PositionWhitespacePrefix( line, "#!" );
1429
if position = fail and plain_text_mode = false then
1530
return [ false, line ];
1631
fi;
@@ -63,62 +78,62 @@ InstallGlobalFunction( AutoDoc_Type_Of_Item,
6378
function( current_item, type, default_chapter_data )
6479
local item_rec, entries, has_filters, ret_val;
6580
item_rec := current_item;
66-
if PositionSublist( type, "DeclareCategoryCollections") <> fail then
81+
if type = "DeclareCategoryCollections" then
6782
entries := [ "Filt", "categories" ];
6883
ret_val := "<C>true</C> or <C>false</C>";
6984
has_filters := "No";
7085
if not IsBound( item_rec!.arguments ) then
7186
item_rec!.arguments := "obj";
7287
fi;
7388
item_rec!.coll_suffix := true;
74-
elif PositionSublist( type, "DeclareCategory" ) <> fail then
89+
elif type = "DeclareCategory" then
7590
entries := [ "Filt", "categories" ];
7691
ret_val := "<C>true</C> or <C>false</C>";
7792
has_filters := 1;
78-
elif PositionSublist( type, "DeclareRepresentation" ) <> fail then
93+
elif type = "DeclareRepresentation" then
7994
entries := [ "Filt", "categories" ];
8095
ret_val := "<C>true</C> or <C>false</C>";
8196
has_filters := 1;
82-
elif PositionSublist( type, "DeclareAttribute" ) <> fail then
97+
elif type = "DeclareAttribute" then
8398
entries := [ "Attr", "attributes" ];
8499
has_filters := 1;
85-
elif PositionSublist( type, "DeclareProperty" ) <> fail then
100+
elif type = "DeclareProperty" then
86101
entries := [ "Prop", "properties" ];
87102
ret_val := "<C>true</C> or <C>false</C>";
88103
has_filters := 1;
89-
elif PositionSublist( type, "DeclareOperation" ) <> fail then
104+
elif type = "DeclareOperation" then
90105
entries := [ "Oper", "methods" ];
91106
has_filters := "List";
92-
elif PositionSublist( type, "DeclareConstructor" ) <> fail then
107+
elif type = "DeclareConstructor" then
93108
if IsPackageMarkedForLoading( "GAPDoc", ">=1.6.1" ) then
94109
entries := [ "Constr", "methods" ];
95110
else
96111
AutoDoc_PrintWarningForConstructor();
97112
entries := [ "Oper", "methods" ];
98113
fi;
99114
has_filters := "List";
100-
elif PositionSublist( type, "DeclareGlobalFunction" ) <> fail then
115+
elif type = "DeclareGlobalFunction" then
101116
entries := [ "Func", "global_functions" ];
102117
has_filters := "No";
103118
if not IsBound( item_rec!.arguments ) then
104119
item_rec!.arguments := "arg";
105120
fi;
106-
elif PositionSublist( type, "DeclareGlobalVariable" ) <> fail then
121+
elif type = "DeclareGlobalVariable" then
107122
entries := [ "Var", "global_variables" ];
108123
has_filters := "No";
109124
item_rec!.arguments := fail;
110125
item_rec!.return_value := false;
111-
elif PositionSublist( type, "DeclareFilter" ) <> fail then
126+
elif type = "DeclareFilter" then
112127
entries := [ "Filt", "properties" ];
113128
has_filters := "No";
114129
item_rec!.arguments := fail;
115130
item_rec!.return_value := false;
116-
elif PositionSublist( type, "DeclareInfoClass" ) <> fail then
131+
elif type = "DeclareInfoClass" then
117132
entries := [ "InfoClass", "info_classes" ];
118133
has_filters := "No";
119134
item_rec!.arguments := fail;
120135
item_rec!.return_value := false;
121-
elif PositionSublist( type, "KeyDependentOperation" ) <> fail then
136+
elif type = "KeyDependentOperation" then
122137
entries := [ "Oper", "methods" ];
123138
has_filters := 2;
124139
else
@@ -222,7 +237,8 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
222237
position_parentesis, nr_of_attr_loops, i;
223238

224239
## fail is bigger than every integer
225-
declare_position := Minimum( [ PositionSublist( current_line, "Declare" ), PositionSublist( current_line, "KeyDependentOperation" ) ] );
240+
declare_position := Minimum( [ AUTODOC_PositionWhitespacePrefix( current_line, "Declare" ),
241+
AUTODOC_PositionWhitespacePrefix( current_line, "KeyDependentOperation" ) ] );
226242
if declare_position <> fail then
227243
current_item := new_man_item();
228244
current_line := current_line{[ declare_position .. Length( current_line ) ]};
@@ -417,7 +433,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
417433
temp_curr_line := temp_curr_line{[ 1 .. Length( temp_curr_line ) - 1 ]};
418434
fi;
419435
if plain_text_mode = false then
420-
comment_pos := PositionSublist( temp_curr_line, "#!" );
436+
comment_pos := AUTODOC_PositionWhitespacePrefix( temp_curr_line, "#!" );
421437
if comment_pos <> fail then
422438
before_comment := NormalizedWhitespace( temp_curr_line{ [ 1 .. comment_pos - 1 ] } );
423439
if before_comment = "" then
@@ -448,8 +464,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
448464
break;
449465
fi;
450466
##if is comment, simply remove comments.
451-
#! @DONT_SCAN_NEXT_LINE
452-
temp_pos_comment := PositionSublist( temp_curr_line, "#!" );
467+
temp_pos_comment := AUTODOC_PositionWhitespacePrefix( temp_curr_line, "#!" );
453468
if temp_pos_comment <> fail then
454469
temp_curr_line := temp_curr_line{[ temp_pos_comment + 3 .. Length( temp_curr_line ) ]};
455470
Add( temp_string_list, temp_curr_line );
@@ -492,8 +507,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
492507
fi;
493508
incorporate_this_line := plain_text_mode;
494509
if not plain_text_mode then
495-
#! @DONT_SCAN_NEXT_LINE
496-
temp_pos_comment := PositionSublist( temp_curr_line, "#!" );
510+
temp_pos_comment := AUTODOC_PositionWhitespacePrefix( temp_curr_line, "#!" );
497511
if temp_pos_comment <> fail then
498512
incorporate_this_line := true;
499513
temp_curr_line := temp_curr_line{[ temp_pos_comment + 2 .. Length( temp_curr_line ) ]};
@@ -517,12 +531,6 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
517531
end;
518532
end;
519533
command_function_record := rec(
520-
## HACK: Needed for AutoDoc parser to be scanned savely.
521-
## The lines where the AutoDoc comments are
522-
## searched cause problems otherwise.
523-
@DONT_SCAN_NEXT_LINE := function()
524-
ReadLineWithLineCount( filestream );
525-
end,
526534
@DoNotReadRestOfFile := function()
527535
Reset();
528536
rest_of_file_skipped := true;
@@ -764,7 +772,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
764772
if not IsBound( current_item ) then
765773
return;
766774
fi;
767-
comment_pos := PositionSublist( current_line_unedited, "#!" );
775+
comment_pos := AUTODOC_PositionWhitespacePrefix( current_line_unedited, "#!" );
768776
if comment_pos <> fail then
769777
current_line_unedited := current_line_unedited{[ comment_pos + 2 .. Length( current_line_unedited ) ]};
770778
fi;

‎makedoc.g‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
#
66
# SPDX-License-Identifier: GPL-2.0-or-later
77

8-
LoadPackage("AutoDoc");
8+
if fail = LoadPackage("AutoDoc", ">= 2019.07.17") then
9+
Error("AutoDoc 2019.07.17 or newer is required");
10+
fi;
911

1012
AutoDoc( rec(
1113
autodoc := true,

‎tst/worksheets/general.expected/_Chapter_SomeChapter.xml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,17 @@ Third sentence.
129129
</ManSection>
130130

131131

132+
<ManSection Label="ConStabilize">
133+
<Oper Arg="arg" Name="ConStabilize" Label="for IsObject"/>
134+
<Oper Arg="arg1,arg2" Name="ConStabilize" Label="for IsObject, IsObject"/>
135+
<Description>
136+
This documentation should show the first two variants of the function,
137+
but not the third commented out one.
138+
<P/>
139+
</Description>
140+
</ManSection>
141+
142+
132143
</Section>
133144

134145

‎tst/worksheets/general.sheet/worksheet.g‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,15 @@ DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
7878
#! @Group Group1
7979
KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
8080
81+
#! @BeginGroup ConStabilize
82+
#! @Description
83+
#! This documentation should show the first two variants of the function,
84+
#! but not the third commented out one.
85+
DeclareOperation("ConStabilize", [IsObject]);
86+
DeclareOperation("ConStabilize", [IsObject, IsObject]);
87+
#DeclareOperation("ConStabilize", [IsTransformation, IsPosInt]); # should NOT be documented
88+
#! @EndGroup
89+
8190
#############################################################################
8291
#! @Section Testing chunks
8392

0 commit comments

Comments
 (0)