Support documenting DeclareSynonym and DeclareSynonymAttr

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

doc/Comments.autodoc

@@ -90,22 +90,29 @@ function or a variable.
 
 @Index "@ItemType" <C>@ItemType <A>kind</A></C>
 Overrides the kind of manual item created for the following declaration or
-installed method. The supported values are <C>Func</C>, <C>Oper</C>,
-<C>Attr</C>, <C>Prop</C>, and <C>Var</C>.
+installed method. The supported values are <C>Attr</C>, <C>Filt</C>,
+<C>Func</C>, <C>Oper</C>, <C>Prop</C>, and <C>Var</C>.
 
-This is mainly useful for <C>InstallMethod</C>. For a declaration such as
-<C>DeclareAttribute</C> or <C>DeclareProperty</C>, &AutoDoc; already knows the
-correct item type from the declaration itself. But for <C>InstallMethod</C>,
-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 <C>Oper</C>.
+This is mainly useful for <C>InstallMethod</C>, <C>DeclareGlobalName</C>, and
+<C>DeclareSynonym</C>. For other declarations such as <C>DeclareAttribute</C>
+or <C>DeclareProperty</C>, &AutoDoc; already knows the correct item type from
+the declaration itself.
 
-It is also useful for <C>DeclareGlobalName</C>, because that declaration can
+But for <C>InstallMethod</C>, 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 <C>Oper</C>.
+
+It is useful for <C>DeclareGlobalName</C>, because that declaration can
 refer to either a function or a variable. &AutoDoc; defaults such entries to
 <C>Var</C>, but switches to <C>Func</C> as soon as <C>@Arguments</C> or
 <C>@Returns</C> indicates function-style documentation. You can still use
 <C>@ItemType</C> to override this explicitly.
 
+It is useful for <C>DeclareSynonym</C>, because that declaration can
+document a function synonym or a filter synonym. Use <C>@ItemType Filt</C> if
+the synonym should be emitted as a filter-style manual entry.
+
 For example:
 
 ```@listing

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 := "<K>true</K> or <K>false</K>";
         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 := "<K>true</K> or <K>false</K>";
+        elif IsBound( item_rec!.item_type ) and item_rec!.item_type = "Filt" then
+            entries := [ "Filt", "categories" ];
+            ret_val := "<K>true</K> or <K>false</K>";
+        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;

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
 
 #

tst/manual.expected/_Chapter_Comments.xml

@@ -104,22 +104,29 @@ function or a variable.
 <P/>
 <Index Key="@ItemType"><C>@ItemType <A>kind</A></C></Index>
 Overrides the kind of manual item created for the following declaration or
-installed method. The supported values are <C>Func</C>, <C>Oper</C>,
-<C>Attr</C>, <C>Prop</C>, and <C>Var</C>.
+installed method. The supported values are <C>Attr</C>, <C>Filt</C>,
+<C>Func</C>, <C>Oper</C>, <C>Prop</C>, and <C>Var</C>.
 <P/>
-This is mainly useful for <C>InstallMethod</C>. For a declaration such as
-<C>DeclareAttribute</C> or <C>DeclareProperty</C>, &AutoDoc; already knows the
-correct item type from the declaration itself. But for <C>InstallMethod</C>,
-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 <C>Oper</C>.
+This is mainly useful for <C>InstallMethod</C>, <C>DeclareGlobalName</C>, and
+<C>DeclareSynonym</C>. For other declarations such as <C>DeclareAttribute</C>
+or <C>DeclareProperty</C>, &AutoDoc; already knows the correct item type from
+the declaration itself.
 <P/>
-It is also useful for <C>DeclareGlobalName</C>, because that declaration can
+But for <C>InstallMethod</C>, 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 <C>Oper</C>.
+<P/>
+It is useful for <C>DeclareGlobalName</C>, because that declaration can
 refer to either a function or a variable. &AutoDoc; defaults such entries to
 <C>Var</C>, but switches to <C>Func</C> as soon as <C>@Arguments</C> or
 <C>@Returns</C> indicates function-style documentation. You can still use
 <C>@ItemType</C> to override this explicitly.
 <P/>
+It is useful for <C>DeclareSynonym</C>, because that declaration can
+document a function synonym or a filter synonym. Use <C>@ItemType Filt</C> if
+the synonym should be emitted as a filter-style manual entry.
+<P/>
 For example:
 <P/>
 <Listing><![CDATA[

tst/worksheets.tst

@@ -19,6 +19,13 @@ gap> 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 ...

tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<!DOCTYPE Book SYSTEM "gapdoc.dtd"
+[
+    <#Include SYSTEM "_entities.xml">
+]
+>
+<Book Name="Synonym_Declarations_Test">
+<#Include SYSTEM "title.xml">
+<TableOfContents/>
+<Body>
+<#Include SYSTEM "_AutoDocMainFile.xml">
+</Body>
+</Book>

tst/worksheets/synonyms.expected/_AutoDocMainFile.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<#Include SYSTEM "_Chapter_Synonyms_Chapter.xml">

tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<Chapter Label="Chapter_Synonyms_Chapter">
+<Heading>Synonyms Chapter</Heading>
+
+<Section Label="Chapter_Synonyms_Chapter_Section_Synonyms_Section">
+<Heading>Synonyms Section</Heading>
+
+ Worksheet regression for issue #174.
+<ManSection>
+  <Func Arg="arg" Name="SomeFunctionAlias" />
+ <Description>
+ A synonym documented as a function by default.
+ </Description>
+</ManSection>
+
+<ManSection>
+  <Filt Arg="arg" Name="IsSomeFilterAlias" />
+ <Returns><K>true</K> or <K>false</K>
+</Returns>
+ <Description>
+ A synonym documented as a filter.
+ </Description>
+</ManSection>
+
+<ManSection>
+  <Attr Arg="arg" Name="SomeAttributeAlias" />
+ <Description>
+ A synonym attribute.
+ </Description>
+</ManSection>
+
+</Section>
+
+</Chapter>
+

tst/worksheets/synonyms.expected/_entities.xml

@@ -0,0 +1 @@
+<!ENTITY Synonym_Declarations_Test '<Package>Synonym_Declarations_Test</Package>'>

tst/worksheets/synonyms.expected/title.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<TitlePage>
+  <Title>
+    Synonym Declarations Test
+  </Title>
+  <Date>
+    12 March 2026
+  </Date>
+  </TitlePage>

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 );