From 04cf3bc169efce0903ee1d18d9f1a856dd413d5b Mon Sep 17 00:00:00 2001 From: Max Horn Date: Thu, 26 Feb 2026 23:48:24 +0100 Subject: [PATCH] Warn for chunks defined but never inserted Track chunk definition/insertion state and warn when a chunk was defined but never inserted. Resolves #63 Co-authored-by: Codex --- CHANGES.md | 2 ++ gap/DocumentationTree.gi | 12 ++++++++++++ gap/Parser.gi | 2 ++ tst/misc.tst | 16 ++++++++++++++++ 4 files changed, 32 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index c1ee679e..7ca7a5b2 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -15,6 +15,8 @@ This file describes changes in the AutoDoc package. generated test output to temporary directories - Remove `@DONT_SCAN_NEXT_LINE` parser hack and only treat `#!` as an AutoDoc marker at the start of a line (ignoring leading whitespace) + - Warn if a chunk is defined (via `@BeginChunk`/`@BeginCode`) but never + inserted (via `@InsertChunk`/`@InsertCode`) 2025.12.19 - Don't replace empty lines in `@BeginCode` blocks by `

` diff --git a/gap/DocumentationTree.gi b/gap/DocumentationTree.gi index 141ad8f8..eb8e7b74 100644 --- a/gap/DocumentationTree.gi +++ b/gap/DocumentationTree.gi @@ -233,6 +233,8 @@ InstallMethod( DocumentationChunk, [ IsTreeForDocumentation, IsString ], level := tree!.current_level ); ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeChunkNodes, Label, name ); + node!.is_defined := false; + node!.is_inserted := false; tree!.chunks.( name ) := node; return node; end ); @@ -419,6 +421,15 @@ BindGlobal( "WriteChunks", for current_chunk_name in chunk_names do current_chunk := tree!.chunks.( current_chunk_name ); + if current_chunk!.is_defined = true and current_chunk!.is_inserted = false then + Info( + InfoAutoDoc, + 1, + "WARNING: chunk ", + current_chunk_name, + " was defined but never inserted" + ); + fi; AppendTo( chunks_stream, "<#GAPDoc Label=\"", current_chunk_name, "\">\n" ); if IsBound( current_chunk!.content ) then WriteDocumentation( current_chunk!.content, chunks_stream, level_value ); @@ -602,6 +613,7 @@ InstallMethod( WriteDocumentation, [ IsTreeForDocumentationChunkNodeRep, IsStrea if node!.level > level_value then return; fi; + node!.is_inserted := true; WriteDocumentation( Concatenation( "<#Include Label=\"", Label( node ), "\">" ), filestream, level_value ); end ); diff --git a/gap/Parser.gi b/gap/Parser.gi index 7d91bc56..5fa90bbf 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -749,6 +749,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, fi; label_name := ReplacedString( current_command[ 2 ], " ", "_" ); current_item := DocumentationChunk( tree, label_name ); + current_item!.is_defined := true; end, @Chunk := ~.@BeginChunk, @EndChunk := function() @@ -764,6 +765,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, local label_name, tmp_system; label_name := ReplacedString( current_command[ 2 ], " ", "_" ); tmp_system := DocumentationChunk( tree, label_name ); + tmp_system!.is_defined := true; Add( tmp_system!.content, DocumentationChunkContent( read_code() ) ); end, @Code := ~.@BeginCode, diff --git a/tst/misc.tst b/tst/misc.tst index bdf9812c..07cfe8fc 100644 --- a/tst/misc.tst +++ b/tst/misc.tst @@ -112,5 +112,21 @@ gap> item!.tester_names; gap> item!.arguments; "x,y" +# +# warn about defined-but-never-inserted chunks +# +gap> tmpdir := Filename(DirectoryTemporary(), "autodoc-unusedchunk-test");; +gap> if IsDirectoryPath(tmpdir) then RemoveDirectoryRecursively(tmpdir); fi; +gap> AUTODOC_CreateDirIfMissing(tmpdir); +true +gap> tree2 := DocumentationTree();; +gap> chunk := DocumentationChunk(tree2, "NeverUsed");; +gap> chunk!.is_defined := true;; +gap> Add(chunk!.content, "Some text");; +gap> WriteDocumentation(tree2, Directory(tmpdir), 0); +#I WARNING: chunk NeverUsed was defined but never inserted +gap> RemoveDirectoryRecursively(tmpdir); +true + # gap> STOP_TEST( "misc.tst" );