Allow documenting function via comment on DeclareGlobalName

CHANGES.md

@@ -37,6 +37,9 @@ This file describes changes in the AutoDoc package.
   - 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
   - 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

doc/Comments.autodoc

@@ -80,13 +80,18 @@ square brackets for the optional arguments, like <Q>grp[, elm]</Q> or
 <Q>xx[y[z] ]</Q>. If &GAP; options are used, this can be followed by a colon :
 and one or more assignments, like <Q>n[, r]: tries := 100</Q>.
 
+For <C>DeclareGlobalName</C>, using <C>@Arguments</C> or <C>@Returns</C> also
+makes &AutoDoc; document the item as a function. This is useful because
+<C>DeclareGlobalName</C> itself does not reveal whether the name denotes a
+function or a variable.
+
 @Subsection <C>@ItemType <A>kind</A></C>
 @SubsectionLabel @ItemType
 
 @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>, and <C>Prop</C>.
+<C>Attr</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
@@ -95,6 +100,12 @@ 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 also 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.
+
 For example:
 
 ```@listing

gap/Parser.gi

@@ -173,10 +173,19 @@ InstallGlobalFunction( AutoDoc_Type_Of_Item,
         item_rec!.arguments := fail;
         item_rec!.return_value := false;
     elif PositionSublist( type, "DeclareGlobalName" ) <> fail then
-        entries := [ "Var", "global_variables" ];
         has_filters := "No";
-        item_rec!.arguments := fail;
-        item_rec!.return_value := false;
+        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;
+        fi;
     elif PositionSublist( type, "DeclareFilter" ) <> fail then
         entries := [ "Filt", "properties" ];
         has_filters := "No";
@@ -422,13 +431,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" ] then
+        if item_type in [ "Func", "Oper", "Attr", "Prop", "Var" ] then
             return item_type;
         fi;
         ErrorWithPos(
             Concatenation(
                 "unknown @ItemType ", item_type,
-                "; expected one of Func, Oper, Attr, Prop"
+                "; expected one of Func, Oper, Attr, Prop, Var"
             )
         );
     end;
@@ -806,12 +815,26 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
         @Returns := function()
             CurrentOrNewManItem();
             CurrentItem()!.content := CurrentItem()!.return_value;
+            if IsBound( CurrentItem()!.item_type ) and CurrentItem()!.item_type = "Var" then
+                CurrentItem()!.item_type := "Func";
+                if not IsBound( CurrentItem()!.arguments ) or CurrentItem()!.arguments = fail then
+                    CurrentItem()!.arguments := "arg";
+                fi;
+                CurrentItem()!.return_value := [ ];
+            elif not IsBound( CurrentItem()!.item_type ) then
+                CurrentItem()!.declareglobalname_is_function := true;
+            fi;
             if current_command[ 2 ] <> "" then
                 Add( CurrentItem(), current_command[ 2 ] );
             fi;
         end,
         @Arguments := function()
             CurrentOrNewManItem();
+            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;
+            fi;
             CurrentItem()!.arguments := current_command[ 2 ];
         end,
         @ItemType := function()

tst/errorwithpos.tst

@@ -89,7 +89,7 @@ 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,
+Error, unknown @ItemType Method; expected one of Func, Oper, Attr, Prop, Var,
 at tst/errorwithpos/itemtype-unknown.g:3
 
 #

tst/manual.expected/_Chapter_Comments.xml

@@ -91,6 +91,11 @@ square brackets for the optional arguments, like <Q>grp[, elm]</Q> or
 <Q>xx[y[z] ]</Q>. If &GAP; options are used, this can be followed by a colon :
 and one or more assignments, like <Q>n[, r]: tries := 100</Q>.
 <P/>
+For <C>DeclareGlobalName</C>, using <C>@Arguments</C> or <C>@Returns</C> also
+makes &AutoDoc; document the item as a function. This is useful because
+<C>DeclareGlobalName</C> itself does not reveal whether the name denotes a
+function or a variable.
+<P/>
 </Subsection>
 
 <Subsection Label="Subsection_@ItemType">
@@ -100,7 +105,7 @@ and one or more assignments, like <Q>n[, r]: tries := 100</Q>.
 <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>, and <C>Prop</C>.
+<C>Attr</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
@@ -109,6 +114,12 @@ 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 also 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/>
 For example:
 <P/>
 <Listing><![CDATA[

tst/misc.tst

@@ -122,6 +122,52 @@ gap> item!.tester_names;
 gap> item!.arguments;
 "x,y"
 
+#
+# AutoDoc_Parser_ReadFiles: DeclareGlobalName defaults and overrides
+#
+gap> tmpdir := Filename(DirectoryTemporary(), "autodoc-globalname-test");;
+gap> if IsDirectoryPath(tmpdir) then RemoveDirectoryRecursively(tmpdir); fi;
+gap> AUTODOC_CreateDirIfMissing(tmpdir);
+true
+gap> tmpdir_obj := Directory(tmpdir);;
+gap> file := Filename(tmpdir_obj, "globalname.gd");;
+gap> stream := OutputTextFile(file, false);;
+gap> AppendTo(stream, "#! @Chapter Parser\n");;
+gap> AppendTo(stream, "#! @Section GlobalName\n");;
+gap> AppendTo(stream, "#! @Description\n");;
+gap> AppendTo(stream, "DeclareGlobalName( \"DefaultGlobalName\" );\n");;
+gap> AppendTo(stream, "#! @Description\n");;
+gap> AppendTo(stream, "#! @Arguments x\n");;
+gap> AppendTo(stream, "DeclareGlobalName( \"ArgumentGlobalName\" );\n");;
+gap> AppendTo(stream, "#! @Description\n");;
+gap> AppendTo(stream, "#! @Returns a value\n");;
+gap> AppendTo(stream, "DeclareGlobalName( \"ReturnGlobalName\" );\n");;
+gap> AppendTo(stream, "#! @Description\n");;
+gap> AppendTo(stream, "#! @ItemType Var\n");;
+gap> AppendTo(stream, "DeclareGlobalName( \"VariableGlobalName\" );\n");;
+gap> CloseStream(stream);
+gap> tree := DocumentationTree();;
+gap> AutoDoc_Parser_ReadFiles( [ file ], tree, rec() );
+gap> section := SectionInTree( tree, "Parser", "GlobalName" );;
+gap> section!.content[ 1 ]!.item_type;
+"Var"
+gap> section!.content[ 1 ]!.arguments = fail;
+true
+gap> section!.content[ 2 ]!.item_type;
+"Func"
+gap> section!.content[ 2 ]!.arguments;
+"x"
+gap> section!.content[ 3 ]!.item_type;
+"Func"
+gap> section!.content[ 3 ]!.arguments;
+"arg"
+gap> section!.content[ 4 ]!.item_type;
+"Var"
+gap> section!.content[ 4 ]!.arguments = fail;
+true
+gap> RemoveDirectoryRecursively(tmpdir);
+true
+
 #
 # warn about defined-but-never-inserted chunks
 #

tst/worksheets/general.expected/_Chapter_SomeChapter.xml

@@ -202,7 +202,14 @@ This text will only appear in the HTML version and the text version.
 <ManSection>
   <Var Name="SomeGlobalName" />
  <Description>
- A global name
+ A global name documented as a variable by default
+ </Description>
+</ManSection>
+
+<ManSection>
+  <Func Arg="x" Name="SomeGlobalNameFunction" />
+ <Description>
+ A global name documented as a function once arguments are given
  </Description>
 </ManSection>
 

tst/worksheets/general.sheet/worksheet.g

@@ -135,9 +135,14 @@ DeclareGlobalFunction( "SomeGlobalFunction" );
 DeclareGlobalVariable( "SomeGlobalVariable" );
 
 #! @Description
-#! A global name
+#! A global name documented as a variable by default
 DeclareGlobalName( "SomeGlobalName" );
 
+#! @Description
+#! A global name documented as a function once arguments are given
+#! @Arguments x
+DeclareGlobalName( "SomeGlobalNameFunction" );
+
 #! @Description
 #! A filter
 DeclareFilter( "SomeFilter" );