Skip to content

Ignore commented out declarations #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fingolfin wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Ignore commented out declarations #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGES
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ This file describes changes in the AutoDoc package.

2019.07.xx
- Fix bug in extract_examples option that could result in invalid .tst files
- Fix bug where commented out declarations still appeared in the manual.

2019.07.03
- Make Chunks compatible with GAPDoc chunks
Expand Down
62 changes: 35 additions & 27 deletions gap/Parser.gi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,27 @@
#
# SPDX-License-Identifier: GPL-2.0-or-later

## Check if the string <line> starts with whitespaces followed by <prefix>; if
## this is the case, returns the start position of <prefix>, otherwise fail.
BindGlobal( "AUTODOC_PositionWhitespacePrefix",
function( line, prefix )
local position;
# ignore leading whitespace
position := PositionProperty( line, x -> not x in " \t" );
if position = fail or position+Length(prefix)-1 > Length(line) then
return fail;
fi;
if line{[position..position+Length(prefix)-1]} = prefix then
return position;
fi;
return fail;
end );

##
InstallGlobalFunction( Scan_for_AutoDoc_Part,
function( line, plain_text_mode )
local position, whitespace_position, command, argument;
#! @DONT_SCAN_NEXT_LINE
position := PositionSublist( line, "#!" );
position := AUTODOC_PositionWhitespacePrefix( line, "#!" );
if position = fail and plain_text_mode = false then
return [ false, line ];
fi;
Expand Down Expand Up @@ -63,62 +78,62 @@ InstallGlobalFunction( AutoDoc_Type_Of_Item,
function( current_item, type, default_chapter_data )
local item_rec, entries, has_filters, ret_val;
item_rec := current_item;
if PositionSublist( type, "DeclareCategoryCollections") <> fail then
if type = "DeclareCategoryCollections" then
entries := [ "Filt", "categories" ];
ret_val := "<C>true</C> or <C>false</C>";
has_filters := "No";
if not IsBound( item_rec!.arguments ) then
item_rec!.arguments := "obj";
fi;
item_rec!.coll_suffix := true;
elif PositionSublist( type, "DeclareCategory" ) <> fail then
elif type = "DeclareCategory" then
entries := [ "Filt", "categories" ];
ret_val := "<C>true</C> or <C>false</C>";
has_filters := 1;
elif PositionSublist( type, "DeclareRepresentation" ) <> fail then
elif type = "DeclareRepresentation" then
entries := [ "Filt", "categories" ];
ret_val := "<C>true</C> or <C>false</C>";
has_filters := 1;
elif PositionSublist( type, "DeclareAttribute" ) <> fail then
elif type = "DeclareAttribute" then
entries := [ "Attr", "attributes" ];
has_filters := 1;
elif PositionSublist( type, "DeclareProperty" ) <> fail then
elif type = "DeclareProperty" then
entries := [ "Prop", "properties" ];
ret_val := "<C>true</C> or <C>false</C>";
has_filters := 1;
elif PositionSublist( type, "DeclareOperation" ) <> fail then
elif type = "DeclareOperation" then
entries := [ "Oper", "methods" ];
has_filters := "List";
elif PositionSublist( type, "DeclareConstructor" ) <> fail then
elif type = "DeclareConstructor" then
if IsPackageMarkedForLoading( "GAPDoc", ">=1.6.1" ) then
entries := [ "Constr", "methods" ];
else
AutoDoc_PrintWarningForConstructor();
entries := [ "Oper", "methods" ];
fi;
has_filters := "List";
elif PositionSublist( type, "DeclareGlobalFunction" ) <> fail then
elif type = "DeclareGlobalFunction" then
entries := [ "Func", "global_functions" ];
has_filters := "No";
if not IsBound( item_rec!.arguments ) then
item_rec!.arguments := "arg";
fi;
elif PositionSublist( type, "DeclareGlobalVariable" ) <> fail then
elif type = "DeclareGlobalVariable" then
entries := [ "Var", "global_variables" ];
has_filters := "No";
item_rec!.arguments := fail;
item_rec!.return_value := false;
elif PositionSublist( type, "DeclareFilter" ) <> fail then
elif type = "DeclareFilter" then
entries := [ "Filt", "properties" ];
has_filters := "No";
item_rec!.arguments := fail;
item_rec!.return_value := false;
elif PositionSublist( type, "DeclareInfoClass" ) <> fail then
elif type = "DeclareInfoClass" then
entries := [ "InfoClass", "info_classes" ];
has_filters := "No";
item_rec!.arguments := fail;
item_rec!.return_value := false;
elif PositionSublist( type, "KeyDependentOperation" ) <> fail then
elif type = "KeyDependentOperation" then
entries := [ "Oper", "methods" ];
has_filters := 2;
else
Expand Down Expand Up @@ -222,7 +237,8 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
position_parentesis, nr_of_attr_loops, i;

## fail is bigger than every integer
declare_position := Minimum( [ PositionSublist( current_line, "Declare" ), PositionSublist( current_line, "KeyDependentOperation" ) ] );
declare_position := Minimum( [ AUTODOC_PositionWhitespacePrefix( current_line, "Declare" ),
AUTODOC_PositionWhitespacePrefix( current_line, "KeyDependentOperation" ) ] );
if declare_position <> fail then
current_item := new_man_item();
current_line := current_line{[ declare_position .. Length( current_line ) ]};
Expand Down Expand Up @@ -417,7 +433,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
temp_curr_line := temp_curr_line{[ 1 .. Length( temp_curr_line ) - 1 ]};
fi;
if plain_text_mode = false then
comment_pos := PositionSublist( temp_curr_line, "#!" );
comment_pos := AUTODOC_PositionWhitespacePrefix( temp_curr_line, "#!" );
if comment_pos <> fail then
before_comment := NormalizedWhitespace( temp_curr_line{ [ 1 .. comment_pos - 1 ] } );
if before_comment = "" then
Expand Down Expand Up @@ -448,8 +464,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
break;
fi;
##if is comment, simply remove comments.
#! @DONT_SCAN_NEXT_LINE
temp_pos_comment := PositionSublist( temp_curr_line, "#!" );
temp_pos_comment := AUTODOC_PositionWhitespacePrefix( temp_curr_line, "#!" );
if temp_pos_comment <> fail then
temp_curr_line := temp_curr_line{[ temp_pos_comment + 3 .. Length( temp_curr_line ) ]};
Add( temp_string_list, temp_curr_line );
Expand Down Expand Up @@ -492,8 +507,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
fi;
incorporate_this_line := plain_text_mode;
if not plain_text_mode then
#! @DONT_SCAN_NEXT_LINE
temp_pos_comment := PositionSublist( temp_curr_line, "#!" );
temp_pos_comment := AUTODOC_PositionWhitespacePrefix( temp_curr_line, "#!" );
if temp_pos_comment <> fail then
incorporate_this_line := true;
temp_curr_line := temp_curr_line{[ temp_pos_comment + 2 .. Length( temp_curr_line ) ]};
Expand All @@ -517,12 +531,6 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
end;
end;
command_function_record := rec(
## HACK: Needed for AutoDoc parser to be scanned savely.
## The lines where the AutoDoc comments are
## searched cause problems otherwise.
@DONT_SCAN_NEXT_LINE := function()
ReadLineWithLineCount( filestream );
end,
Copy link
Member Author

@fingolfin fingolfin Jul 17, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Being able to get rid of @DONT_SCAN_NEXT_LINE is a nice side benefit, IMHO.

@DoNotReadRestOfFile := function()
Reset();
rest_of_file_skipped := true;
Expand Down Expand Up @@ -764,7 +772,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
if not IsBound( current_item ) then
return;
fi;
comment_pos := PositionSublist( current_line_unedited, "#!" );
comment_pos := AUTODOC_PositionWhitespacePrefix( current_line_unedited, "#!" );
if comment_pos <> fail then
current_line_unedited := current_line_unedited{[ comment_pos + 2 .. Length( current_line_unedited ) ]};
fi;
Expand Down
4 changes: 3 additions & 1 deletion makedoc.g
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@
#
# SPDX-License-Identifier: GPL-2.0-or-later

LoadPackage("AutoDoc");
if fail = LoadPackage("AutoDoc", ">= 2019.07.17") then
Error("AutoDoc 2019.07.17 or newer is required");
fi;

AutoDoc( rec(
autodoc := true,
Expand Down
11 changes: 11 additions & 0 deletions tst/worksheets/general.expected/_Chapter_SomeChapter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,17 @@ Third sentence.
</ManSection>


<ManSection Label="ConStabilize">
<Oper Arg="arg" Name="ConStabilize" Label="for IsObject"/>
<Oper Arg="arg1,arg2" Name="ConStabilize" Label="for IsObject, IsObject"/>
<Description>
This documentation should show the first two variants of the function,
but not the third commented out one.
<P/>
</Description>
</ManSection>


</Section>


Expand Down
9 changes: 9 additions & 0 deletions tst/worksheets/general.sheet/worksheet.g
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,15 @@ DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
#! @Group Group1
KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );

#! @BeginGroup ConStabilize
#! @Description
#! This documentation should show the first two variants of the function,
#! but not the third commented out one.
DeclareOperation("ConStabilize", [IsObject]);
DeclareOperation("ConStabilize", [IsObject, IsObject]);
#DeclareOperation("ConStabilize", [IsTransformation, IsPosInt]); # should NOT be documented
#! @EndGroup

#############################################################################
#! @Section Testing chunks

Expand Down