From c91b196e10b0288b5ba403bdd822be7f91888e90 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Fri, 13 Mar 2026 01:47:13 +0100 Subject: [PATCH 1/2] Refactor item type metadata Centralize manual item type metadata, add support for Constr, Fam, InfoClass, Meth, and the Cat, Coll, and Repr aliases, and fix filter default chapter buckets. Change InstallMethod and InstallOtherMethod to document entries as Meth by default, update XML emission to use metadata-driven GAPDoc tags, and refresh docs and expected outputs. AI disclosure: Codex assisted with implementation, documentation updates, and test fixture regeneration. Co-authored-by: Codex --- CHANGES.md | 14 +- doc/Comments.autodoc | 34 ++-- gap/AutoDocMainFunction.gi | 8 +- gap/Parser.gd | 1 + gap/Parser.gi | 189 +++++++++++------- gap/ToolFunctions.gi | 15 +- .../manual.expected/_Chapter_SourceAPI.xml | 2 +- tst/errorwithpos.tst | 4 +- tst/manual.expected/_Chapter_Comments.xml | 34 ++-- tst/worksheets.tst | 4 +- .../general.expected/_Chapter_SomeChapter.xml | 14 +- .../Item_Type_Metadata_Test.xml} | 2 +- .../_AutoDocMainFile.xml | 2 +- .../_Chapter_Item_Types_Chapter.xml | 99 +++++++++ .../_Chunks.xml | 0 .../item-type-metadata.expected/_entities.xml | 1 + .../title.xml | 2 +- .../item-type-metadata.sheet/worksheet.g | 69 +++++++ .../_Chapter_Synonyms_Chapter.xml | 37 ---- .../synonyms.expected/_entities.xml | 1 - tst/worksheets/synonyms.sheet/worksheet.g | 18 -- 21 files changed, 366 insertions(+), 184 deletions(-) rename tst/worksheets/{synonyms.expected/Synonym_Declarations_Test.xml => item-type-metadata.expected/Item_Type_Metadata_Test.xml} (87%) rename tst/worksheets/{synonyms.expected => item-type-metadata.expected}/_AutoDocMainFile.xml (63%) create mode 100644 tst/worksheets/item-type-metadata.expected/_Chapter_Item_Types_Chapter.xml rename tst/worksheets/{synonyms.expected => item-type-metadata.expected}/_Chunks.xml (100%) create mode 100644 tst/worksheets/item-type-metadata.expected/_entities.xml rename tst/worksheets/{synonyms.expected => item-type-metadata.expected}/title.xml (85%) create mode 100644 tst/worksheets/item-type-metadata.sheet/worksheet.g delete mode 100644 tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml delete mode 100644 tst/worksheets/synonyms.expected/_entities.xml delete mode 100644 tst/worksheets/synonyms.sheet/worksheet.g diff --git a/CHANGES.md b/CHANGES.md index e5bd15c3..583df9e4 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -11,6 +11,8 @@ This file describes changes in the AutoDoc package. - Only document the first declaration immediately following an AutoDoc source comment block; later consecutive declarations now require their own `#!` comment block + - When documenting an `InstallMethod`, we now use the item type `Meth` + instead of `Oper` + **New Features** - Add `nopdf` as a global option, and document the existing `NOPDF` @@ -19,6 +21,8 @@ This file describes changes in the AutoDoc package. `@Chapter`/`@Section`/`@Subsection` in `.autodoc` files and doc comments - Add support for documenting `DeclareSynonym` and `DeclareSynonymAttr` declarations + - Add `@ItemType` to override the type of a declaration, which is + especially useful for `DeclareSynonym` or `DeclareGlobalName` - Add fenced code blocks using triple backticks or tildes in Markdown-like text; `@listing`, `@example`, and `@log` info strings select the corresponding GAPDoc element @@ -31,6 +35,9 @@ This file describes changes in the AutoDoc package. nested source directories are picked up automatically + **Other Changes** + - Improve `DeclareGlobalName` handling: document it as a variable by + default, but switch to a function when `@Arguments` or `@Returns` + provides function-style documentation - Ignore trailing blank lines after single-line worksheet title-page commands such as `@Title`, `@Subtitle`, `@Version`, `@Author`, and `@Date`, and trim trailing blank lines from generated title-page @@ -53,12 +60,7 @@ This file describes changes in the AutoDoc package. `@Command` does not start at column 1 - Normalize parsed `InstallMethod` names by stripping surrounding quotes, matching `Declare...` handling - - Document `InstallMethod` support in declaration comments and add - `@ItemType` to override whether an installed method should be - documented as `Func`, `Oper`, `Attr`, or `Prop` - - Improve `DeclareGlobalName` handling: document it as a variable by - default, but switch to a function when `@Arguments` or `@Returns` - provides function-style documentation + - Document `InstallMethod` support in declaration comments - Loosen requirements on `@Date` command: this used to allow free form, but in recent versions was restricted to dates of the form YYYY-MM-DD or DD/MM/YYYY; now we again allow any text, but text in those specific diff --git a/doc/Comments.autodoc b/doc/Comments.autodoc index b58122a3..219426b4 100644 --- a/doc/Comments.autodoc +++ b/doc/Comments.autodoc @@ -90,18 +90,19 @@ 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 Attr, Filt, -Func, Oper, Prop, and Var. +installed method. The supported values are Attr, Cat, +Coll, Constr, Fam, Filt, Func, +InfoClass, Meth, Oper, Prop, Repr, +and Var. -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. +The values Cat, Coll, and Repr are &AutoDoc;-specific +aliases. They emit Filt entries with the corresponding &GAPDoc; filter +type. -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 useful when the source code alone does not determine which manual item +kind should be emitted. For many declarations such as DeclareAttribute +or DeclareProperty, &AutoDoc; already knows the intended type from the +declaration itself. It is useful for DeclareGlobalName, because that declaration can refer to either a function or a variable. &AutoDoc; defaults such entries to @@ -110,18 +111,19 @@ refer to either a function or a variable. &AutoDoc; defaults such entries to @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. +document a function synonym or one of several filter-like synonyms. Use +@ItemType Filt, Cat, Coll, or Repr to control which +kind of filter entry should be emitted. For example: ```@listing -#! @ItemType Attr -InstallMethod( SomeAttribute, [ IsGroup ], G -> G ); +#! @ItemType Repr +DeclareSynonym( "IsSomethingRep", IsComponentObjectRep ); ``` -This makes &AutoDoc; emit an <Attr .../> manual entry instead of -the default <Oper .../>. +This makes &AutoDoc; emit a +<Filt Type="Representation" .../> manual entry. @Subsection @Group grpname @SubsectionLabel @Group diff --git a/gap/AutoDocMainFunction.gi b/gap/AutoDocMainFunction.gi index f6c3392b..80215fc5 100644 --- a/gap/AutoDocMainFunction.gi +++ b/gap/AutoDocMainFunction.gi @@ -47,8 +47,12 @@ InstallGlobalFunction( CreateDefaultChapterData, chapter_name := Concatenation( pkgname, "_automatic_generated_documentation" ); default_chapter_record := rec(); - list_of_types := [ "categories", "methods", "attributes", "properties", - "global_functions", "global_variables", "info_classes" ]; + list_of_types := Set( + List( + RecNames( AUTODOC_ITEM_TYPE_INFO ), + n -> AUTODOC_ITEM_TYPE_INFO.( n ).chapter_bucket + ) + ); for i in list_of_types do default_chapter_record.(i) := [ chapter_name, Concatenation( chapter_name, "_of_", i ) ]; diff --git a/gap/Parser.gd b/gap/Parser.gd index edc4a7c1..2970e828 100644 --- a/gap/Parser.gd +++ b/gap/Parser.gd @@ -7,6 +7,7 @@ DeclareGlobalFunction( "Scan_for_AutoDoc_Part" ); DeclareGlobalFunction( "AutoDoc_Type_Of_Item" ); +DeclareGlobalName( "AUTODOC_ITEM_TYPE_INFO" ); ## Argument should be a filename DeclareGlobalFunction( "AutoDoc_Parser_ReadFiles" ); diff --git a/gap/Parser.gi b/gap/Parser.gi index 11d15ef3..1497d00c 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -5,6 +5,68 @@ # # SPDX-License-Identifier: GPL-2.0-or-later +## +BindGlobal( "AUTODOC_ITEM_TYPE_INFO", rec( + Attr := rec( + chapter_bucket := "attributes", + is_function_like := true + ), + Cat := rec( + chapter_bucket := "categories", + filter_type := "Category", + item_type_override := "Filt", + is_function_like := true + ), + Coll := rec( + chapter_bucket := "collections", + filter_type := "Collection", + item_type_override := "Filt", + is_function_like := true + ), + Constr := rec( + chapter_bucket := "methods", + is_function_like := true + ), + Fam := rec( + chapter_bucket := "global_variables", + is_function_like := false + ), + Filt := rec( + chapter_bucket := "filters", + is_function_like := true + ), + Func := rec( + chapter_bucket := "global_functions", + is_function_like := true + ), + InfoClass := rec( + chapter_bucket := "info_classes", + is_function_like := false + ), + Meth := rec( + chapter_bucket := "methods", + is_function_like := true + ), + Oper := rec( + chapter_bucket := "methods", + is_function_like := true + ), + Prop := rec( + chapter_bucket := "properties", + is_function_like := true + ), + Repr := rec( + chapter_bucket := "representations", + filter_type := "Representation", + item_type_override := "Filt", + is_function_like := true + ), + Var := rec( + chapter_bucket := "global_variables", + is_function_like := false + ) +)); + ## BindGlobal( "AUTODOC_PositionPrefixShebang", function( line ) @@ -130,113 +192,93 @@ end ); ## InstallGlobalFunction( AutoDoc_Type_Of_Item, function( current_item, type, default_chapter_data ) - local item_rec, entries, filter_style, ret_val; + local item_rec, filter_style, default_type, item_type, item_type_info, + default_boolean_return; item_rec := current_item; + default_boolean_return := "true or false"; if PositionSublist( type, "DeclareCategoryCollections") <> fail then - entries := [ "Filt", "categories" ]; - ret_val := "true or false"; + default_type := "Coll"; filter_style := "none"; 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 := "true or false"; + default_type := "Cat"; filter_style := "single"; elif PositionSublist( type, "DeclareRepresentation" ) <> fail then - entries := [ "Filt", "categories" ]; - ret_val := "true or false"; + default_type := "Repr"; filter_style := "single"; elif PositionSublist( type, "DeclareAttribute" ) <> fail then - entries := [ "Attr", "attributes" ]; + default_type := "Attr"; filter_style := "single"; elif PositionSublist( type, "DeclareSynonymAttr" ) <> fail then - entries := [ "Attr", "attributes" ]; + default_type := "Attr"; 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"; + default_type := "Prop"; filter_style := "single"; elif PositionSublist( type, "DeclareSynonym" ) <> fail then + default_type := "Func"; 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" ]; + default_type := "Oper"; filter_style := "list"; elif PositionSublist( type, "DeclareConstructor" ) <> fail then - entries := [ "Constr", "methods" ]; + default_type := "Constr"; filter_style := "list"; elif PositionSublist( type, "DeclareGlobalFunction" ) <> fail then - entries := [ "Func", "global_functions" ]; + default_type := "Func"; filter_style := "none"; - if not IsBound( item_rec!.arguments ) then - item_rec!.arguments := "arg"; - fi; elif PositionSublist( type, "DeclareGlobalVariable" ) <> fail then - entries := [ "Var", "global_variables" ]; + default_type := "Var"; filter_style := "none"; - item_rec!.arguments := fail; - item_rec!.return_value := false; elif PositionSublist( type, "DeclareGlobalName" ) <> fail then + default_type := "Var"; filter_style := "none"; - if ( IsBound( item_rec!.item_type ) and item_rec!.item_type <> "Var" ) or - ( IsBound( item_rec!.declareglobalname_is_function ) and - item_rec!.declareglobalname_is_function ) then - entries := [ "Func", "global_functions" ]; - if not IsBound( item_rec!.arguments ) then - item_rec!.arguments := "arg"; - fi; - else - entries := [ "Var", "global_variables" ]; - item_rec!.arguments := fail; - item_rec!.return_value := false; + if IsBound( item_rec!.declaration_is_function ) and + item_rec!.declaration_is_function then + default_type := "Func"; fi; elif PositionSublist( type, "DeclareFilter" ) <> fail then - entries := [ "Filt", "properties" ]; + default_type := "Filt"; filter_style := "none"; - item_rec!.arguments := fail; - item_rec!.return_value := false; elif PositionSublist( type, "DeclareInfoClass" ) <> fail then - entries := [ "InfoClass", "info_classes" ]; + default_type := "InfoClass"; filter_style := "none"; - item_rec!.arguments := fail; - item_rec!.return_value := false; elif PositionSublist( type, "KeyDependentOperation" ) <> fail then - entries := [ "Oper", "methods" ]; + default_type := "Oper"; filter_style := "pair"; else return fail; fi; - item_rec!.item_type := entries[ 1 ]; + + if IsBound( item_rec!.item_type ) then + item_type := StripBeginEnd( item_rec!.item_type, " \t\r\n" ); + else + item_type := default_type; + fi; + if not IsBound( AUTODOC_ITEM_TYPE_INFO.( item_type ) ) then + return fail; + fi; + item_type_info := AUTODOC_ITEM_TYPE_INFO.( item_type ); + item_rec!.item_type := item_type; + if not IsBound( item_rec!.chapter_info ) or item_rec!.chapter_info = [ ] then - item_rec!.chapter_info := default_chapter_data.( entries[ 2 ] ); + item_rec!.chapter_info := + default_chapter_data.( item_type_info.chapter_bucket ); fi; - if IsBound( ret_val ) and ( item_rec!.return_value = [ ] or item_rec!.return_value = false ) then - item_rec!.return_value := [ ret_val ]; + + if item_type in [ "Cat", "Coll", "Filt", "Prop", "Repr" ] and + ( item_rec!.return_value = [ ] or item_rec!.return_value = false ) then + item_rec!.return_value := [ default_boolean_return ]; + fi; + if filter_style = "none" and item_type_info.is_function_like and + not IsBound( item_rec!.arguments ) then + item_rec!.arguments := "arg"; + elif filter_style = "none" and not item_type_info.is_function_like then + item_rec!.arguments := fail; + item_rec!.return_value := false; fi; return filter_style; end ); @@ -462,14 +504,19 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, fi; end; NormalizeItemType := function( item_type ) + local supported_types; item_type := StripBeginEnd( item_type, " \t\r\n" ); - if item_type in [ "Attr", "Filt", "Func", "Oper", "Prop", "Var" ] then + if IsBound( AUTODOC_ITEM_TYPE_INFO.( item_type ) ) then return item_type; fi; + supported_types := JoinStringsWithSeparator( + Set( RecNames( AUTODOC_ITEM_TYPE_INFO ) ), + ", " + ); ErrorWithPos( Concatenation( "unknown @ItemType ", item_type, - "; expected one of Attr, Filt, Func, Oper, Prop, Var" + "; expected one of ", supported_types ) ); end; @@ -592,7 +639,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, local filter_string, name, pos; CurrentOrNewManItem(); if not IsBound( CurrentItem()!.item_type ) then - CurrentItem()!.item_type := "Oper"; + CurrentItem()!.item_type := "Meth"; else CurrentItem()!.item_type := NormalizeItemType( CurrentItem()!.item_type @@ -857,7 +904,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, fi; CurrentItem()!.return_value := [ ]; elif not IsBound( CurrentItem()!.item_type ) then - CurrentItem()!.declareglobalname_is_function := true; + CurrentItem()!.declaration_is_function := true; fi; if current_command[ 2 ] <> "" then Add( CurrentItem(), current_command[ 2 ] ); @@ -868,7 +915,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, if IsBound( CurrentItem()!.item_type ) and CurrentItem()!.item_type = "Var" then CurrentItem()!.item_type := "Func"; elif not IsBound( CurrentItem()!.item_type ) then - CurrentItem()!.declareglobalname_is_function := true; + CurrentItem()!.declaration_is_function := true; fi; CurrentItem()!.arguments := current_command[ 2 ]; end, diff --git a/gap/ToolFunctions.gi b/gap/ToolFunctions.gi index 896381b6..ba0ebc90 100644 --- a/gap/ToolFunctions.gi +++ b/gap/ToolFunctions.gi @@ -63,7 +63,8 @@ end ); ## InstallGlobalFunction( AutoDoc_WriteDocEntry, function( filestream, list_of_records, heading ) - local return_value, description, current_description, labels, i; + local return_value, description, current_description, labels, i, + item_type_info; # look for a good return value (it should be the same everywhere) for i in list_of_records do @@ -122,10 +123,18 @@ InstallGlobalFunction( AutoDoc_WriteDocEntry, # Function headers for i in list_of_records do - AppendTo( filestream, " <", i!.item_type, " " ); - if i!.arguments <> fail and i!.item_type <> "Var" then + item_type_info := AUTODOC_ITEM_TYPE_INFO.( i!.item_type ); + if IsBound( item_type_info.item_type_override ) then + AppendTo( filestream, " <", item_type_info.item_type_override, " " ); + else + AppendTo( filestream, " <", i!.item_type, " " ); + fi; + if item_type_info.is_function_like and i!.arguments <> fail then AppendTo( filestream, "Arg=\"", i!.arguments, "\" " ); fi; + if IsBound( item_type_info.filter_type ) then + AppendTo( filestream, "Type=\"", item_type_info.filter_type, "\" " ); + fi; AppendTo( filestream, "Name=\"", i!.name, "\" " ); if i!.tester_names <> fail and i!.tester_names <> "" then AppendTo( filestream, "Label=\"", i!.tester_names, "\"" ); diff --git a/tst/AutoDocTest/tst/manual.expected/_Chapter_SourceAPI.xml b/tst/AutoDocTest/tst/manual.expected/_Chapter_SourceAPI.xml index 7f7d6ef1..e310947c 100644 --- a/tst/AutoDocTest/tst/manual.expected/_Chapter_SourceAPI.xml +++ b/tst/AutoDocTest/tst/manual.expected/_Chapter_SourceAPI.xml @@ -83,7 +83,7 @@

A method installation without an itemtype - +

diff --git a/tst/errorwithpos.tst b/tst/errorwithpos.tst index 4489f895..07cf9e2a 100644 --- a/tst/errorwithpos.tst +++ b/tst/errorwithpos.tst @@ -89,8 +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 Attr, Filt, Func, Oper, Prop,\ - Var, +Error, unknown @ItemType Method; expected one of Attr, Cat, Coll, Constr, Fam,\ + Filt, Func, InfoClass, Meth, Oper, Prop, Repr, 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 459dc547..a6690c1f 100644 --- a/tst/manual.expected/_Chapter_Comments.xml +++ b/tst/manual.expected/_Chapter_Comments.xml @@ -104,18 +104,19 @@ function or a variable.

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

-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. +The values Cat, Coll, and Repr are &AutoDoc;-specific +aliases. They emit Filt entries with the corresponding &GAPDoc; filter +type.

-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 useful when the source code alone does not determine which manual item +kind should be emitted. For many declarations such as DeclareAttribute +or DeclareProperty, &AutoDoc; already knows the intended type from the +declaration itself.

It is useful for DeclareGlobalName, because that declaration can refer to either a function or a variable. &AutoDoc; defaults such entries to @@ -124,18 +125,19 @@ refer to either a function or a variable. &AutoDoc; defaults such entries to @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. +document a function synonym or one of several filter-like synonyms. Use +@ItemType Filt, Cat, Coll, or Repr to control which +kind of filter entry should be emitted.

For example:

G ); +#! @ItemType Repr +DeclareSynonym( "IsSomethingRep", IsComponentObjectRep ); ]]>

-This makes &AutoDoc; emit an <Attr .../> manual entry instead of -the default <Oper .../>. +This makes &AutoDoc; emit a +<Filt Type="Representation" .../> manual entry.

diff --git a/tst/worksheets.tst b/tst/worksheets.tst index 4232bc6c..23048599 100644 --- a/tst/worksheets.tst +++ b/tst/worksheets.tst @@ -20,8 +20,8 @@ gap> AUTODOC_TestWorkSheet("consecutive-declarations"); #I no examples # -gap> AUTODOC_TestWorkSheet("synonyms"); -#I Extracting manual examples for Synonym Declarations Test package ... +gap> AUTODOC_TestWorkSheet("item-type-metadata"); +#I Extracting manual examples for Item Type Metadata Test package ... #I 1 chapters detected #I Chapter 1... #I no examples diff --git a/tst/worksheets/general.expected/_Chapter_SomeChapter.xml b/tst/worksheets/general.expected/_Chapter_SomeChapter.xml index 3dc96a40..6366f069 100644 --- a/tst/worksheets/general.expected/_Chapter_SomeChapter.xml +++ b/tst/worksheets/general.expected/_Chapter_SomeChapter.xml @@ -39,7 +39,7 @@ gap> comment_mode_value := 6 * Intro text - + true or false @@ -48,7 +48,7 @@ gap> comment_mode_value := 6 * - + true or false @@ -57,7 +57,7 @@ gap> comment_mode_value := 6 * - + true or false @@ -135,7 +135,7 @@ This text will only appear in the HTML version and the text version. Testing various kinds of documentation - + true or false @@ -144,7 +144,7 @@ This text will only appear in the HTML version and the text version. - + true or false @@ -214,7 +214,9 @@ This text will only appear in the HTML version and the text version. - + + true or false + A filter diff --git a/tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml b/tst/worksheets/item-type-metadata.expected/Item_Type_Metadata_Test.xml similarity index 87% rename from tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml rename to tst/worksheets/item-type-metadata.expected/Item_Type_Metadata_Test.xml index 6dd264b1..873f348c 100644 --- a/tst/worksheets/synonyms.expected/Synonym_Declarations_Test.xml +++ b/tst/worksheets/item-type-metadata.expected/Item_Type_Metadata_Test.xml @@ -6,7 +6,7 @@ <#Include SYSTEM "_entities.xml"> ] > - + <#Include SYSTEM "title.xml"> diff --git a/tst/worksheets/synonyms.expected/_AutoDocMainFile.xml b/tst/worksheets/item-type-metadata.expected/_AutoDocMainFile.xml similarity index 63% rename from tst/worksheets/synonyms.expected/_AutoDocMainFile.xml rename to tst/worksheets/item-type-metadata.expected/_AutoDocMainFile.xml index 38fccd5d..4a3c524f 100644 --- a/tst/worksheets/synonyms.expected/_AutoDocMainFile.xml +++ b/tst/worksheets/item-type-metadata.expected/_AutoDocMainFile.xml @@ -1,4 +1,4 @@ -<#Include SYSTEM "_Chapter_Synonyms_Chapter.xml"> +<#Include SYSTEM "_Chapter_Item_Types_Chapter.xml"> diff --git a/tst/worksheets/item-type-metadata.expected/_Chapter_Item_Types_Chapter.xml b/tst/worksheets/item-type-metadata.expected/_Chapter_Item_Types_Chapter.xml new file mode 100644 index 00000000..62925244 --- /dev/null +++ b/tst/worksheets/item-type-metadata.expected/_Chapter_Item_Types_Chapter.xml @@ -0,0 +1,99 @@ + + + + +Item Types Chapter + +

+Type Overrides + + Worksheet regression for item-type metadata and issue #174. + + + + A synonym documented as a function by default. + + + + + + true or false + + + A synonym documented as a filter. + + + + + + true or false + + + A synonym documented as a category. + + + + + + true or false + + + A synonym documented as a collection. + + + + + + true or false + + + A synonym documented as a representation. + + + + + + + A family-like global name. + + + + + + + An info class-like global name. + + + + + + + A method documented as a method by default. + + + + + + + A method documented as a constructor. + + + + + + + An explicit method override. + + + + + + + A synonym attribute. + + + +
+ + + diff --git a/tst/worksheets/synonyms.expected/_Chunks.xml b/tst/worksheets/item-type-metadata.expected/_Chunks.xml similarity index 100% rename from tst/worksheets/synonyms.expected/_Chunks.xml rename to tst/worksheets/item-type-metadata.expected/_Chunks.xml diff --git a/tst/worksheets/item-type-metadata.expected/_entities.xml b/tst/worksheets/item-type-metadata.expected/_entities.xml new file mode 100644 index 00000000..ef693734 --- /dev/null +++ b/tst/worksheets/item-type-metadata.expected/_entities.xml @@ -0,0 +1 @@ +Item_Type_Metadata_Test'> diff --git a/tst/worksheets/synonyms.expected/title.xml b/tst/worksheets/item-type-metadata.expected/title.xml similarity index 85% rename from tst/worksheets/synonyms.expected/title.xml rename to tst/worksheets/item-type-metadata.expected/title.xml index cabcf678..57edf4d2 100644 --- a/tst/worksheets/synonyms.expected/title.xml +++ b/tst/worksheets/item-type-metadata.expected/title.xml @@ -3,7 +3,7 @@ - Synonym Declarations Test + Item Type Metadata Test 12 March 2026 diff --git a/tst/worksheets/item-type-metadata.sheet/worksheet.g b/tst/worksheets/item-type-metadata.sheet/worksheet.g new file mode 100644 index 00000000..4e68fd8a --- /dev/null +++ b/tst/worksheets/item-type-metadata.sheet/worksheet.g @@ -0,0 +1,69 @@ +#! @Title Item Type Metadata Test +#! @Date 2026-03-12 +#! @Chapter Item Types Chapter +#! @Section Type Overrides +#! Worksheet regression for item-type metadata and 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 +#! @ItemType Cat +#! A synonym documented as a category. +DeclareSynonym( "IsSomeCategoryAlias", IsObject ); + +#! @Description +#! @ItemType Coll +#! A synonym documented as a collection. +DeclareSynonym( "IsSomeCollectionAlias", IsObject ); + +#! @Description +#! @ItemType Repr +#! A synonym documented as a representation. +DeclareSynonym( "IsSomeRepresentationAlias", IsComponentObjectRep ); + +#! @Description +#! A family-like global name. +#! @ItemType Fam +DeclareGlobalName( "SomeFamilyAlias" ); + +#! @Description +#! An info class-like global name. +#! @ItemType InfoClass +DeclareGlobalName( "SomeInfoClassAlias" ); + +#! @Description +#! A method documented as a method by default. +InstallMethod( "SomeInstalledMethod", + [ IsObject, IsInt ], + function( obj, n ) + return obj; + end ); + +#! @Description +#! @ItemType Constr +#! A method documented as a constructor. +InstallMethod( "SomeInstalledConstructor", + [ IsObject ], + function( obj ) + return obj; + end ); + +#! @Description +#! @ItemType Meth +#! An explicit method override. +InstallMethod( "SomeExplicitMethod", + [ IsObject ], + function( obj ) + return obj; + end ); + +#! @Description +#! A synonym attribute. +DeclareSynonymAttr( "SomeAttributeAlias", SomeAttribute ); diff --git a/tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml b/tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml deleted file mode 100644 index 820fd336..00000000 --- a/tst/worksheets/synonyms.expected/_Chapter_Synonyms_Chapter.xml +++ /dev/null @@ -1,37 +0,0 @@ - - - - -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/_entities.xml b/tst/worksheets/synonyms.expected/_entities.xml deleted file mode 100644 index 8bab7bc5..00000000 --- a/tst/worksheets/synonyms.expected/_entities.xml +++ /dev/null @@ -1 +0,0 @@ -Synonym_Declarations_Test'> diff --git a/tst/worksheets/synonyms.sheet/worksheet.g b/tst/worksheets/synonyms.sheet/worksheet.g deleted file mode 100644 index cb911523..00000000 --- a/tst/worksheets/synonyms.sheet/worksheet.g +++ /dev/null @@ -1,18 +0,0 @@ -#! @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 ); From d1b89d33a7e10797fd1be9b31bede496cda38c3b Mon Sep 17 00:00:00 2001 From: Max Horn Date: Fri, 13 Mar 2026 02:43:36 +0100 Subject: [PATCH 2/2] WIP --- gap/Parser.gd | 3 ++- gap/Parser.gi | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/gap/Parser.gd b/gap/Parser.gd index 2970e828..a5eb1fdb 100644 --- a/gap/Parser.gd +++ b/gap/Parser.gd @@ -7,7 +7,8 @@ DeclareGlobalFunction( "Scan_for_AutoDoc_Part" ); DeclareGlobalFunction( "AutoDoc_Type_Of_Item" ); -DeclareGlobalName( "AUTODOC_ITEM_TYPE_INFO" ); + +DeclareGlobalVariable( "AUTODOC_ITEM_TYPE_INFO" ); ## Argument should be a filename DeclareGlobalFunction( "AutoDoc_Parser_ReadFiles" ); diff --git a/gap/Parser.gi b/gap/Parser.gi index 1497d00c..2c08bfde 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -6,7 +6,7 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -BindGlobal( "AUTODOC_ITEM_TYPE_INFO", rec( +InstallValue( AUTODOC_ITEM_TYPE_INFO, rec( Attr := rec( chapter_bucket := "attributes", is_function_like := true