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..a5eb1fdb 100644 --- a/gap/Parser.gd +++ b/gap/Parser.gd @@ -8,5 +8,7 @@ DeclareGlobalFunction( "Scan_for_AutoDoc_Part" ); DeclareGlobalFunction( "AutoDoc_Type_Of_Item" ); +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 11d15ef3..2c08bfde 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -5,6 +5,68 @@ # # SPDX-License-Identifier: GPL-2.0-or-later +## +InstallValue( 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 );