Skip to content

Handle documentation of DeclareCategoryCollection declarations. #171

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

Merged
fingolfin merged 1 commit into from
May 21, 2019
Merged

Handle documentation of DeclareCategoryCollection declarations. #171

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
33 changes: 31 additions & 2 deletions gap/Parser.gi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,15 @@ 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, "DeclareCategory" ) <> fail then
if PositionSublist( type, "DeclareCategoryCollections") <> fail 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
entries := [ "Filt", "categories" ];
ret_val := "<C>true</C> or <C>false</C>";
has_filters := 1;
Expand Down Expand Up @@ -229,7 +237,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
return false;
fi;
current_line := current_line{ [ position_parentesis + 1 .. Length( current_line ) ] };
## Not the funny part begins:
## Now the funny part begins:
Copy link
Copy Markdown

@sebasguts sebasguts May 21, 2019

Choose a reason for hiding this comment

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

Hehe, nice.

## try fetching the name:
## Assuming the name is in the same line as its
while PositionSublist( current_line, "," ) = fail and PositionSublist( current_line, ");" ) = fail do
Expand All @@ -238,6 +246,27 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
current_line := StripBeginEnd( current_line, " " );
current_item!.name := current_line{ [ 1 .. Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) - 1 ] };
current_item!.name := StripBeginEnd( ReplacedString( current_item!.name, "\"", "" ), " " );

# Deal with DeclareCategoryCollections: this has some special
# rules on how the name of a new category is derived from the
# string given to it. Since the code for that is not available in
# a separate GAP function, we have to replicate this logic here.
# To understand what's going on, please refer to the
# DeclareCategoryCollections documentation and implementation.
if IsBound(current_item!.coll_suffix) then
if EndsWith(current_item!.name, "Collection") then
current_item!.name :=
current_item!.name{[1..Length(current_item!.name)-6]};
fi;
if EndsWith(current_item!.name, "Coll") then
current_item!.coll_suffix := "Coll";
else
current_item!.coll_suffix := "Collection";
fi;
current_item!.name := Concatenation(current_item!.name,
current_item!.coll_suffix);
fi;
Copy link
Copy Markdown

@sebasguts sebasguts May 21, 2019

Choose a reason for hiding this comment

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

Can you please explain what this if does?

To me it seems like you check if the item ends with Collection, you do nothing. If it ends with Coll, you add another Coll to the name?

Specially, in the docs below it seems like MyThingsColl gets a manual entry MyThingsCollColl, which seems wrong . . .

Copy link
Copy Markdown
Member

@fingolfin fingolfin May 21, 2019

Choose a reason for hiding this comment

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

As explained in the PR description and the commit message, this imitates the behavior of DeclareCategoryCollections. I recommend looking at the code for DeclareCategoryCollections (and the comment before it) in the GAP library. Let me know if there are still questions after that :-).

That said, I think there should be a comment here which explains that; I can add one later.

Copy link
Copy Markdown

@sebasguts sebasguts May 21, 2019

Choose a reason for hiding this comment

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

I see . . .

Okay, sorry for the confusion.

Copy link
Copy Markdown
Member

@fingolfin fingolfin May 21, 2019

Choose a reason for hiding this comment

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

No confusion, nothing to be sorry about: you raised a valid point. I've now added a comment, which hopefully makes this code easier to understand for future generations (e.g. us, two years down the road ;-).

Copy link
Copy Markdown
Member

@fingolfin fingolfin May 21, 2019

Choose a reason for hiding this comment

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

I will also submit a PR to GAP to actually document DeclareCategoryCollections, which lots of packages use...

In the meantime, feel free to approve this PR ;-)


current_line := current_line{ [ Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) + 1 .. Length( current_line ) ] };
filter_string := "for ";
## FIXME: The next two if's can be merged at some point
Expand Down
48 changes: 48 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 @@ -14,6 +14,54 @@ gap> Size(S5);


And we wrap up with some dummy text
<Section Label="Chapter_SomeChapter_Section_Some_categories">
<Heading>Some categories</Heading>

Intro text
<ManSection>
<Filt Arg="arg" Name="MyThings" Label="for IsObject"/>
<Returns><C>true</C> or <C>false</C>
</Returns>
<Description>
<P/>
</Description>
</ManSection>


<ManSection>
<Filt Arg="obj" Name="MyThingsCollection" />
<Returns><C>true</C> or <C>false</C>
</Returns>
<Description>
<P/>
</Description>
</ManSection>


<ManSection>
<Filt Arg="obj" Name="MyThingsCollColl" />
<Returns><C>true</C> or <C>false</C>
</Returns>
<Description>
<P/>
</Description>
</ManSection>


<ManSection>
<Filt Arg="obj" Name="MyThingsCollColl" />
<Returns><C>true</C> or <C>false</C>
</Returns>
<Description>
<P/>
</Description>
</ManSection>


Let's wrap up with something, though.
</Section>


<Section Label="Chapter_SomeChapter_Section_SomeSection">
<Heading>SomeSection</Heading>

Expand Down
10 changes: 10 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 @@ -22,6 +22,16 @@ Print( "(Even though we never use it that way.\n" );
#! @EndExampleSession
#! And we wrap up with some dummy text

#! @Section Some categories
#! Intro text
DeclareCategory("MyThings", IsObject);
DeclareCategoryCollections("MyThings");
DeclareCategoryCollections("MyThingsColl");
DeclareCategoryCollections("MyThingsCollection");
Now here is some text with a bunch of &!$%*!/ weird things in it. But that
should be OK, nothing should end up in a weird place.
#! Let's wrap up with something, though.

#! @Section SomeSection

#! Some test just inside a section. We can use test some markdown features here:
Expand Down