gap-packages · fingolfin · Mar 12, 2026 · Mar 11, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -8,6 +8,9 @@ This file describes changes in the AutoDoc package.
     documented. Since nobody ever reported issues with them, and since
     no distributed packages uses them, they probably are simply not in
     use anywhere. Hence the removal instead of trying to fix this.
+  - Only document the first declaration immediately following an AutoDoc
+    source comment block; later consecutive declarations now require their
+    own `#!` comment block
 
 + **New Features**
   - Add `nopdf` as a global option, and document the existing `NOPDF`

diff --git a/gap/Parser.gi b/gap/Parser.gi
@@ -1201,8 +1201,9 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
                 continue;
             fi;
             current_line := current_command[ 2 ];
-            if autodoc_read_line and not ScanForDeclarationPart( ) then
+            if autodoc_read_line then
                 autodoc_read_line := false;
+                ScanForDeclarationPart( );
             fi;
         od;
         CloseStream( filestream );

diff --git a/tst/misc.tst b/tst/misc.tst
@@ -333,5 +333,36 @@ gap> section!.content[3];
 gap> RemoveDirectoryRecursively(tmpdir);
 true
 
+#
+# only the first declaration after an AutoDoc comment is documented
+# see https://github.com/gap-packages/AutoDoc/issues/169
+#
+gap> tmpdir := Filename(DirectoryTemporary(), "autodoc-consecutive-declarations-test");;
+gap> if IsDirectoryPath(tmpdir) then RemoveDirectoryRecursively(tmpdir); fi;
+gap> AUTODOC_CreateDirIfMissing(tmpdir);
+true
+gap> tmpdir_obj := Directory(tmpdir);;
+gap> file1 := Filename(tmpdir_obj, "consecutive.gd");;
+gap> stream := OutputTextFile(file1, false);;
+gap> AppendTo(stream, "#! @Chapter Parser\n");;
+gap> AppendTo(stream, "#! @Section Consecutive Declarations\n");;
+gap> AppendTo(stream, "#! @Description\n");;
+gap> AppendTo(stream, "#!  Only this declaration should be documented.\n");;
+gap> AppendTo(stream, "DeclareGlobalFunction( \"Foo\" );\n");;
+gap> AppendTo(stream, "DeclareGlobalFunction( \"Bar\" );\n");;
+gap> CloseStream(stream);
+gap> tree6 := DocumentationTree();;
+gap> AutoDoc_Parser_ReadFiles([file1], tree6, rec());
+gap> section := SectionInTree(tree6, "Parser", "Consecutive_Declarations");;
+gap> Length(section!.content);
+1
+gap> item := section!.content[1];;
+gap> item!.name;
+"Foo"
+gap> item!.description;
+[ "  Only this declaration should be documented.\n" ]
+gap> RemoveDirectoryRecursively(tmpdir);
+true
+
 #
 gap> STOP_TEST( "misc.tst" );
diff --git a/tst/worksheets.tst b/tst/worksheets.tst
@@ -12,6 +12,13 @@ gap> AUTODOC_TestWorkSheet("general");
 #I  Chapter 2...
 #I  no examples
 
+#
+gap> AUTODOC_TestWorkSheet("consecutive-declarations");
+#I  Extracting manual examples for Consecutive 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/consecutive-declarations.expected/Consecutive_Declarations_Test.xml b/tst/worksheets/consecutive-declarations.expected/Consecutive_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="Consecutive_Declarations_Test">
+<#Include SYSTEM "title.xml">
+<TableOfContents/>
+<Body>
+<#Include SYSTEM "_AutoDocMainFile.xml">
+</Body>
+</Book>
diff --git a/tst/worksheets/consecutive-declarations.expected/_AutoDocMainFile.xml b/tst/worksheets/consecutive-declarations.expected/_AutoDocMainFile.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<#Include SYSTEM "_Chapter_Consecutive_Chapter.xml">
diff --git a/tst/worksheets/consecutive-declarations.expected/_Chapter_Consecutive_Chapter.xml b/tst/worksheets/consecutive-declarations.expected/_Chapter_Consecutive_Chapter.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<Chapter Label="Chapter_Consecutive_Chapter">
+<Heading>Consecutive Chapter</Heading>
+
+<Section Label="Chapter_Consecutive_Chapter_Section_Consecutive_Section">
+<Heading>Consecutive Section</Heading>
+
+ Worksheet regression for issue #169.
+<ManSection>
+  <Func Arg="arg" Name="FirstConsecutiveFunction" />
+ <Description>
+ First declaration stays documented.
+ </Description>
+</ManSection>
+
+<ManSection>
+  <Func Arg="arg" Name="ThirdConsecutiveFunction" />
+ <Description>
+ Third declaration has its own comment block.
+ </Description>
+</ManSection>
+
+</Section>
+
+</Chapter>
+
diff --git a/tst/worksheets/consecutive-declarations.expected/_Chunks.xml b/tst/worksheets/consecutive-declarations.expected/_Chunks.xml
diff --git a/tst/worksheets/consecutive-declarations.expected/_entities.xml b/tst/worksheets/consecutive-declarations.expected/_entities.xml
@@ -0,0 +1 @@
+<!ENTITY Consecutive_Declarations_Test '<Package>Consecutive_Declarations_Test</Package>'>
diff --git a/tst/worksheets/consecutive-declarations.expected/title.xml b/tst/worksheets/consecutive-declarations.expected/title.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<TitlePage>
+  <Title>
+    Consecutive Declarations Test
+  </Title>
+  <Date>
+    12 March 2026
+  </Date>
+  </TitlePage>
diff --git a/tst/worksheets/consecutive-declarations.sheet/worksheet.g b/tst/worksheets/consecutive-declarations.sheet/worksheet.g
@@ -0,0 +1,14 @@
+#! @Title Consecutive Declarations Test
+#! @Date 2026-03-12
+#! @Chapter Consecutive Chapter
+#! @Section Consecutive Section
+#! Worksheet regression for issue #169.
+
+#! @Description
+#! First declaration stays documented.
+DeclareGlobalFunction( "FirstConsecutiveFunction" );
+DeclareGlobalFunction( "SecondConsecutiveFunction" );
+
+#! @Description
+#! Third declaration has its own comment block.
+DeclareGlobalFunction( "ThirdConsecutiveFunction" );
diff --git a/tst/worksheets/general.sheet/worksheet.g b/tst/worksheets/general.sheet/worksheet.g
@@ -41,7 +41,9 @@ comment_mode_value := 6 *
 #! @Section Some categories
 #!  Intro text
 DeclareCategory("MyThings", IsObject);
+#! @Description
 DeclareCategoryCollections("MyThings");
+#! @Description
 DeclareCategoryCollections("MyThingsCollection");
 # Now here is some text with a bunch of &!$%*!/ weird things in it. But that
 # should be OK, nothing should end up in a weird place.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<!ENTITY Consecutive_Declarations_Test '<Package>Consecutive_Declarations_Test</Package>'>