Warn for chunks defined but never inserted

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 `<P/>`

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 );
 

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,

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" );