From c160538c50e0429de9127eae58dbc566790daf08 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Thu, 12 Mar 2026 22:58:14 +0100 Subject: [PATCH] parser: support synonym declarations Support documenting DeclareSynonym and DeclareSynonymAttr, and support @ItemType Filt for filter-style synonyms. AI disclosure: Codex assisted with implementation, documentation updates, and test coverage. Fixes #174. Co-authored-by: Codex --- CHANGES.md | 2 + doc/Comments.autodoc | 25 ++++++++----- gap/Parser.gi | 33 ++++++++++++++++- tst/errorwithpos.tst | 3 +- tst/manual.expected/_Chapter_Comments.xml | 25 ++++++++----- tst/worksheets.tst | 7 ++++ .../Synonym_Declarations_Test.xml | 15 ++++++++ .../synonyms.expected/_AutoDocMainFile.xml | 4 ++ .../_Chapter_Synonyms_Chapter.xml | 37 +++++++++++++++++++ tst/worksheets/synonyms.expected/_Chunks.xml | 0 .../synonyms.expected/_entities.xml | 1 + tst/worksheets/synonyms.expected/title.xml | 11 ++++++ tst/worksheets/synonyms.sheet/worksheet.g | 18 +++++++++ 13 files changed, 160 insertions(+), 21 deletions(-) create mode 100644 tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml create mode 100644 tst/worksheets/synonyms.expected/_AutoDocMainFile.xml create mode 100644 tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml create mode 100644 tst/worksheets/synonyms.expected/_Chunks.xml create mode 100644 tst/worksheets/synonyms.expected/_entities.xml create mode 100644 tst/worksheets/synonyms.expected/title.xml create mode 100644 tst/worksheets/synonyms.sheet/worksheet.g diff --git a/CHANGES.md b/CHANGES.md index e384ca70..e5bd15c3 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -17,6 +17,8 @@ This file describes changes in the AutoDoc package. environment variable and `relativePath` global option - Add Markdown-style headings `#`/`##`/`###` as aliases for `@Chapter`/`@Section`/`@Subsection` in `.autodoc` files and doc comments + - Add support for documenting `DeclareSynonym` and + `DeclareSynonymAttr` declarations - Add fenced code blocks using triple backticks or tildes in Markdown-like text; `@listing`, `@example`, and `@log` info strings select the corresponding GAPDoc element diff --git a/doc/Comments.autodoc b/doc/Comments.autodoc index 52a4aa95..b58122a3 100644 --- a/doc/Comments.autodoc +++ b/doc/Comments.autodoc @@ -90,22 +90,29 @@ function or a variable. @Index "@ItemType" @ItemType kind Overrides the kind of manual item created for the following declaration or -installed method. The supported values are Func, Oper, -Attr, Prop, and Var. +installed method. The supported values are Attr, Filt, +Func, Oper, Prop, and Var. -This is mainly useful for InstallMethod. For a declaration such as -DeclareAttribute or DeclareProperty, &AutoDoc; already knows the -correct item type from the declaration itself. But for InstallMethod, -especially with one argument, the source code alone does not reliably tell -whether the method belongs to an operation, an attribute, a property, or even -a plain function. Without an override, such entries default to Oper. +This is mainly useful for InstallMethod, DeclareGlobalName, and +DeclareSynonym. For other declarations such as DeclareAttribute +or DeclareProperty, &AutoDoc; already knows the correct item type from +the declaration itself. -It is also useful for DeclareGlobalName, because that declaration can +But for InstallMethod, especially with one argument, the source code +alone does not reliably tell whether the method belongs to an operation, an +attribute, a property, or even a plain function. Without an override, such +entries default to Oper. + +It is useful for DeclareGlobalName, because that declaration can refer to either a function or a variable. &AutoDoc; defaults such entries to Var, but switches to Func as soon as @Arguments or @Returns indicates function-style documentation. You can still use @ItemType to override this explicitly. +It is useful for DeclareSynonym, because that declaration can +document a function synonym or a filter synonym. Use @ItemType Filt if +the synonym should be emitted as a filter-style manual entry. + For example: ```@listing diff --git a/gap/Parser.gi b/gap/Parser.gi index f1030c14..6de0c26a 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -151,10 +151,39 @@ InstallGlobalFunction( AutoDoc_Type_Of_Item, elif PositionSublist( type, "DeclareAttribute" ) <> fail then entries := [ "Attr", "attributes" ]; filter_style := "single"; + elif PositionSublist( type, "DeclareSynonymAttr" ) <> fail then + entries := [ "Attr", "attributes" ]; + filter_style := "none"; + if not IsBound( item_rec!.arguments ) then + item_rec!.arguments := "arg"; + fi; elif PositionSublist( type, "DeclareProperty" ) <> fail then entries := [ "Prop", "properties" ]; ret_val := "true or false"; filter_style := "single"; + elif PositionSublist( type, "DeclareSynonym" ) <> fail then + filter_style := "none"; + if IsBound( item_rec!.item_type ) and item_rec!.item_type = "Attr" then + entries := [ "Attr", "attributes" ]; + elif IsBound( item_rec!.item_type ) and item_rec!.item_type = "Prop" then + entries := [ "Prop", "properties" ]; + ret_val := "true or false"; + elif IsBound( item_rec!.item_type ) and item_rec!.item_type = "Filt" then + entries := [ "Filt", "categories" ]; + ret_val := "true or false"; + elif IsBound( item_rec!.item_type ) and item_rec!.item_type = "Oper" then + entries := [ "Oper", "methods" ]; + elif IsBound( item_rec!.item_type ) and item_rec!.item_type = "Var" then + entries := [ "Var", "global_variables" ]; + item_rec!.arguments := fail; + item_rec!.return_value := false; + else + entries := [ "Func", "global_functions" ]; + fi; + if entries[ 1 ] in [ "Func", "Oper", "Attr", "Prop", "Filt" ] and + not IsBound( item_rec!.arguments ) then + item_rec!.arguments := "arg"; + fi; elif PositionSublist( type, "DeclareOperation" ) <> fail then entries := [ "Oper", "methods" ]; filter_style := "list"; @@ -431,13 +460,13 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, end; NormalizeItemType := function( item_type ) item_type := StripBeginEnd( item_type, " \t\r\n" ); - if item_type in [ "Func", "Oper", "Attr", "Prop", "Var" ] then + if item_type in [ "Attr", "Filt", "Func", "Oper", "Prop", "Var" ] then return item_type; fi; ErrorWithPos( Concatenation( "unknown @ItemType ", item_type, - "; expected one of Func, Oper, Attr, Prop, Var" + "; expected one of Attr, Filt, Func, Oper, Prop, Var" ) ); end; diff --git a/tst/errorwithpos.tst b/tst/errorwithpos.tst index 7bbff9a9..4489f895 100644 --- a/tst/errorwithpos.tst +++ b/tst/errorwithpos.tst @@ -89,7 +89,8 @@ gap> ParseFixture( "tst/errorwithpos/installmethod-unterminated-arguments.g" ); Error, unterminated argument list in InstallMethod declaration, at tst/errorwithpos/installmethod-unterminated-arguments.g:4 gap> ParseFixture( "tst/errorwithpos/itemtype-unknown.g" ); -Error, unknown @ItemType Method; expected one of Func, Oper, Attr, Prop, Var, +Error, unknown @ItemType Method; expected one of Attr, Filt, Func, Oper, Prop,\ + Var, at tst/errorwithpos/itemtype-unknown.g:3 # diff --git a/tst/manual.expected/_Chapter_Comments.xml b/tst/manual.expected/_Chapter_Comments.xml index 98256063..459dc547 100644 --- a/tst/manual.expected/_Chapter_Comments.xml +++ b/tst/manual.expected/_Chapter_Comments.xml @@ -104,22 +104,29 @@ function or a variable.

@ItemType kind Overrides the kind of manual item created for the following declaration or -installed method. The supported values are Func, Oper, -Attr, Prop, and Var. +installed method. The supported values are Attr, Filt, +Func, Oper, Prop, and Var.

-This is mainly useful for InstallMethod. For a declaration such as -DeclareAttribute or DeclareProperty, &AutoDoc; already knows the -correct item type from the declaration itself. But for InstallMethod, -especially with one argument, the source code alone does not reliably tell -whether the method belongs to an operation, an attribute, a property, or even -a plain function. Without an override, such entries default to Oper. +This is mainly useful for InstallMethod, DeclareGlobalName, and +DeclareSynonym. For other declarations such as DeclareAttribute +or DeclareProperty, &AutoDoc; already knows the correct item type from +the declaration itself.

-It is also useful for DeclareGlobalName, because that declaration can +But for InstallMethod, especially with one argument, the source code +alone does not reliably tell whether the method belongs to an operation, an +attribute, a property, or even a plain function. Without an override, such +entries default to Oper. +

+It is useful for DeclareGlobalName, because that declaration can refer to either a function or a variable. &AutoDoc; defaults such entries to Var, but switches to Func as soon as @Arguments or @Returns indicates function-style documentation. You can still use @ItemType to override this explicitly.

+It is useful for DeclareSynonym, because that declaration can +document a function synonym or a filter synonym. Use @ItemType Filt if +the synonym should be emitted as a filter-style manual entry. +

For example:

AUTODOC_TestWorkSheet("consecutive-declarations"); #I Chapter 1... #I no examples +# +gap> AUTODOC_TestWorkSheet("synonyms"); +#I Extracting manual examples for Synonym Declarations Test package ... +#I 1 chapters detected +#I Chapter 1... +#I no examples + # gap> AUTODOC_TestWorkSheet("autoplain"); #I Extracting manual examples for Plain file.autodoc Test package ... diff --git a/tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml b/tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml new file mode 100644 index 00000000..6dd264b1 --- /dev/null +++ b/tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml @@ -0,0 +1,15 @@ + + + + +] +> + +<#Include SYSTEM "title.xml"> + + +<#Include SYSTEM "_AutoDocMainFile.xml"> + + diff --git a/tst/worksheets/synonyms.expected/_AutoDocMainFile.xml b/tst/worksheets/synonyms.expected/_AutoDocMainFile.xml new file mode 100644 index 00000000..38fccd5d --- /dev/null +++ b/tst/worksheets/synonyms.expected/_AutoDocMainFile.xml @@ -0,0 +1,4 @@ + + + +<#Include SYSTEM "_Chapter_Synonyms_Chapter.xml"> diff --git a/tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml b/tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml new file mode 100644 index 00000000..820fd336 --- /dev/null +++ b/tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml @@ -0,0 +1,37 @@ + + + + +Synonyms Chapter + +
+Synonyms Section + + Worksheet regression for issue #174. + + + + A synonym documented as a function by default. + + + + + + true or false + + + A synonym documented as a filter. + + + + + + + A synonym attribute. + + + +
+ + + diff --git a/tst/worksheets/synonyms.expected/_Chunks.xml b/tst/worksheets/synonyms.expected/_Chunks.xml new file mode 100644 index 00000000..e69de29b diff --git a/tst/worksheets/synonyms.expected/_entities.xml b/tst/worksheets/synonyms.expected/_entities.xml new file mode 100644 index 00000000..8bab7bc5 --- /dev/null +++ b/tst/worksheets/synonyms.expected/_entities.xml @@ -0,0 +1 @@ +Synonym_Declarations_Test'> diff --git a/tst/worksheets/synonyms.expected/title.xml b/tst/worksheets/synonyms.expected/title.xml new file mode 100644 index 00000000..cabcf678 --- /dev/null +++ b/tst/worksheets/synonyms.expected/title.xml @@ -0,0 +1,11 @@ + + + + + + Synonym Declarations Test + + + 12 March 2026 + + \ No newline at end of file diff --git a/tst/worksheets/synonyms.sheet/worksheet.g b/tst/worksheets/synonyms.sheet/worksheet.g new file mode 100644 index 00000000..cb911523 --- /dev/null +++ b/tst/worksheets/synonyms.sheet/worksheet.g @@ -0,0 +1,18 @@ +#! @Title Synonym Declarations Test +#! @Date 2026-03-12 +#! @Chapter Synonyms Chapter +#! @Section Synonyms Section +#! Worksheet regression for issue #174. + +#! @Description +#! A synonym documented as a function by default. +DeclareSynonym( "SomeFunctionAlias", SomeFunction ); + +#! @Description +#! @ItemType Filt +#! A synonym documented as a filter. +DeclareSynonym( "IsSomeFilterAlias", IsObject ); + +#! @Description +#! A synonym attribute. +DeclareSynonymAttr( "SomeAttributeAlias", SomeAttribute );