docs: Clarify scan_dirs behavior (#345)

Clarify in both the tutorial and reference manual that
autodoc.scan_dirs controls scanning for AutoDoc source comments
and .autodoc files, while gapdoc.scan_dirs only controls scanning
for GAPDoc comments. This also corrects the tutorial examples to
use the autodoc record for the documented behavior.

Fixes #263

AI assistance was provided by Codex for reviewing the existing
documentation, drafting the wording changes, and updating the
generated manual fixtures.

Co-authored-by: Codex <[email protected]>

Author: fingolfin

doc/Tutorials.autodoc

@@ -275,22 +275,27 @@ LoadPackage( "AutoDoc" );
 AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
 ```
 
-As explained above, by default &AutoDoc; scans all <F>.g</F>, <F>.gd</F> and <F>.gi</F> files
-it can find inside of your package root directory, and in the subdirectories <F>gap</F>,
-<F>lib</F>, <F>examples</F> and <F>examples/doc</F> as well.
-If you keep source files with documentation in other directories,
-you can adjust the list of directories AutoDoc scans via the <C>scan_dirs</C> option.
-The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory <F>package_sources</F>
-of the package's root directory.
+&AutoDoc; can scan directories for documentation input automatically.
+In fact there are two separate scanning steps.
+The option <C>autodoc.scan_dirs</C> controls where it looks for source comments beginning with
+<C>#!</C> and for standalone <F>.autodoc</F> files.
+By default, it scans the package root directory and the subdirectories <F>gap</F>,
+<F>lib</F>, <F>examples</F> and <F>examples/doc</F>.
+If you keep that kind of input in other directories, adjust <C>autodoc.scan_dirs</C>.
+The following example instructs &AutoDoc; to only search in the subdirectory
+<F>package_sources</F> of the package's root directory for those files.
 ```@listing
 LoadPackage( "AutoDoc" );
-AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
+AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );
 ```
+The separate option <C>gapdoc.scan_dirs</C> serves a different purpose:
+it controls where &GAPDoc; comments are searched for.
+
 You can also specify an explicit list of files containing documentation,
 which will be searched in addition to any files located within the scan directories:
 ```@listing
 LoadPackage( "AutoDoc" );
-AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
+AutoDoc( rec( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
 ```
 Giving such a file does not prevent the standard <C>scan_dirs</C> from being scanned for
 other files.

gap/Magic.gd

@@ -250,6 +250,10 @@
 #!             A list of subdirectories of the package directory (given as relative paths)
 #!             which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
 #!             are then scanned for &AutoDoc; documentation comments.
+#!             This controls where &AutoDoc; looks for source comments beginning with <C>#!</C>
+#!             and for standalone <F>.autodoc</F> files.
+#!             It does not affect where &GAPDoc; looks for GAPDoc comments; that is controlled
+#!             separately by <A>gapdoc.scan_dirs</A>.
 #!             <Br/>
 #!             <E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
 #!         </Item>
@@ -314,6 +318,9 @@
 #!             A list of subdirectories of the package directory (given as relative paths)
 #!             which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
 #!             are then scanned for &GAPDoc; documentation comments.
+#!             This controls only where &GAPDoc; comments are searched for.
+#!             It does not affect where &AutoDoc; looks for source comments beginning with <C>#!</C>
+#!             or for <F>.autodoc</F> files; use <A>autodoc.scan_dirs</A> for that.
 #!             <Br/>
 #!             <E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
 #!         </Item>

tst/manual.expected/_Chapter_Reference.xml

@@ -267,6 +267,10 @@
              A list of subdirectories of the package directory (given as relative paths)
              which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
              are then scanned for &AutoDoc; documentation comments.
+             This controls where &AutoDoc; looks for source comments beginning with <C>#!</C>
+             and for standalone <F>.autodoc</F> files.
+             It does not affect where &GAPDoc; looks for GAPDoc comments; that is controlled
+             separately by <A>gapdoc.scan_dirs</A>.
              <Br/>
              <E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
          </Item>
@@ -314,6 +318,9 @@
              A list of subdirectories of the package directory (given as relative paths)
              which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
              are then scanned for &GAPDoc; documentation comments.
+             This controls only where &GAPDoc; comments are searched for.
+             It does not affect where &AutoDoc; looks for source comments beginning with <C>#!</C>
+             or for <F>.autodoc</F> files; use <A>autodoc.scan_dirs</A> for that.
              <Br/>
              <E>Default value: <C>[ ".", "gap", "lib", "examples", "examples/doc" ]</C>.</E>
          </Item>

tst/manual.expected/_Chapter_Tutorials.xml

@@ -298,22 +298,27 @@ LoadPackage( "AutoDoc" );
 AutoDoc( rec( gapdoc := rec( main := "main" ) ) );
 ]]></Listing>
 <P/>
-As explained above, by default &AutoDoc; scans all <F>.g</F>, <F>.gd</F> and <F>.gi</F> files
-it can find inside of your package root directory, and in the subdirectories <F>gap</F>,
-<F>lib</F>, <F>examples</F> and <F>examples/doc</F> as well.
-If you keep source files with documentation in other directories,
-you can adjust the list of directories AutoDoc scans via the <C>scan_dirs</C> option.
-The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory <F>package_sources</F>
-of the package's root directory.
+&AutoDoc; can scan directories for documentation input automatically.
+In fact there are two separate scanning steps.
+The option <C>autodoc.scan_dirs</C> controls where it looks for source comments beginning with
+<C>#!</C> and for standalone <F>.autodoc</F> files.
+By default, it scans the package root directory and the subdirectories <F>gap</F>,
+<F>lib</F>, <F>examples</F> and <F>examples/doc</F>.
+If you keep that kind of input in other directories, adjust <C>autodoc.scan_dirs</C>.
+The following example instructs &AutoDoc; to only search in the subdirectory
+<F>package_sources</F> of the package's root directory for those files.
 <Listing><![CDATA[
 LoadPackage( "AutoDoc" );
-AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) );
+AutoDoc( rec( autodoc := rec( scan_dirs := [ "package_sources" ] ) ) );
 ]]></Listing>
+The separate option <C>gapdoc.scan_dirs</C> serves a different purpose:
+it controls where &GAPDoc; comments are searched for.
+<P/>
 You can also specify an explicit list of files containing documentation,
 which will be searched in addition to any files located within the scan directories:
 <Listing><![CDATA[
 LoadPackage( "AutoDoc" );
-AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
+AutoDoc( rec( autodoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) );
 ]]></Listing>
 Giving such a file does not prevent the standard <C>scan_dirs</C> from being scanned for
 other files.