diff --git a/CHANGES.md b/CHANGES.md index 4baf0b4a..e384ca70 100644 --- 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 index 92124f1c..f1030c14 100644 --- 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 index 92575ccc..f0ab7ee7 100644 --- 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 index f397ae88..2f37153b 100644 --- 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 new file mode 100644 index 00000000..c7c79bf2 --- /dev/null +++ b/tst/worksheets/consecutive-declarations.expected/Consecutive_Declarations_Test.xml @@ -0,0 +1,15 @@ + + + + +] +> + +<#Include SYSTEM "title.xml"> + + +<#Include SYSTEM "_AutoDocMainFile.xml"> + + diff --git a/tst/worksheets/consecutive-declarations.expected/_AutoDocMainFile.xml b/tst/worksheets/consecutive-declarations.expected/_AutoDocMainFile.xml new file mode 100644 index 00000000..0e2c7c83 --- /dev/null +++ b/tst/worksheets/consecutive-declarations.expected/_AutoDocMainFile.xml @@ -0,0 +1,4 @@ + + + +<#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 new file mode 100644 index 00000000..3652a5de --- /dev/null +++ b/tst/worksheets/consecutive-declarations.expected/_Chapter_Consecutive_Chapter.xml @@ -0,0 +1,28 @@ + + + + +Consecutive Chapter + +
+Consecutive Section + + Worksheet regression for issue #169. + + + + First declaration stays documented. + + + + + + + Third declaration has its own comment block. + + + +
+ + + diff --git a/tst/worksheets/consecutive-declarations.expected/_Chunks.xml b/tst/worksheets/consecutive-declarations.expected/_Chunks.xml new file mode 100644 index 00000000..e69de29b diff --git a/tst/worksheets/consecutive-declarations.expected/_entities.xml b/tst/worksheets/consecutive-declarations.expected/_entities.xml new file mode 100644 index 00000000..7bc0743b --- /dev/null +++ b/tst/worksheets/consecutive-declarations.expected/_entities.xml @@ -0,0 +1 @@ +Consecutive_Declarations_Test'> diff --git a/tst/worksheets/consecutive-declarations.expected/title.xml b/tst/worksheets/consecutive-declarations.expected/title.xml new file mode 100644 index 00000000..4c68ebd7 --- /dev/null +++ b/tst/worksheets/consecutive-declarations.expected/title.xml @@ -0,0 +1,11 @@ + + + + + + Consecutive Declarations Test + + + 12 March 2026 + + \ No newline at end of file diff --git a/tst/worksheets/consecutive-declarations.sheet/worksheet.g b/tst/worksheets/consecutive-declarations.sheet/worksheet.g new file mode 100644 index 00000000..73ae1ba8 --- /dev/null +++ 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 index 42adcc8f..d356decf 100644 --- 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.