From 0fac96af120a47ed686c26745af50288086e22d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 12 Sep 2023 23:51:26 +0200
Subject: Even more documentation.

---
 doc/ref/calp.texi                               |  1 +
 doc/ref/general.texi                            |  2 +
 doc/ref/general/graph.texi                      | 65 +++++++++++++++++++
 doc/ref/general/options.texi                    | 32 ++++++++++
 doc/ref/introspection.texi                      | 84 +++++++++++++++++++++++++
 module/hnh/module-introspection/all-modules.scm |  2 +-
 6 files changed, 185 insertions(+), 1 deletion(-)
 create mode 100644 doc/ref/general/graph.texi
 create mode 100644 doc/ref/general/options.texi
 create mode 100644 doc/ref/introspection.texi

diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi
index c0a7f3cd..5815d922 100644
--- a/doc/ref/calp.texi
+++ b/doc/ref/calp.texi
@@ -71,6 +71,7 @@ text @footnote{Improvements welcome}
 @include web.texi
 @include text.texi
 @include vulgar.texi
+@include introspection.texi
 
 @node Index
 @unnumbered Index
diff --git a/doc/ref/general.texi b/doc/ref/general.texi
index f42b90f3..d33975ed 100644
--- a/doc/ref/general.texi
+++ b/doc/ref/general.texi
@@ -19,3 +19,5 @@ of these should be generally useful in any project.
 @include general/glob.texi
 @include general/graphviz.texi
 @include general/crypto.texi
+@include general/graph.texi
+@include general/options.texi
diff --git a/doc/ref/general/graph.texi b/doc/ref/general/graph.texi
new file mode 100644
index 00000000..1677b635
--- /dev/null
+++ b/doc/ref/general/graph.texi
@@ -0,0 +1,65 @@
+@node A Graph data structure
+@section A Graph data structure
+
+This is a simple immutable directed graph.
+
+Most operations are O(n), since Scheme lacks a total order betwen
+arbitrary objects.
+
+@defun make-graph [node-key-proc=identity] [node-equal?=eq?]
+Constructs a new graph.
+
+@var{node-key-proc} should be a procedure mapping the actual nodes to
+a value which can be compared. These values are sometimes called
+``node keys''.
+@cindex node keys
+
+@var{node-equal?} should return if two nodes are equal or not.
+@end defun
+
+@defun rebuild-graph [old-graph] [nodes='()] [edges='()]
+@c TODO document me
+@end defun
+
+@defun graph-empty? graph
+Does the graph contaitn
+@end defun
+
+@defun add-node graph node edge-neighbors
+Adds the value @var{node} to @var{graph}. @var{edge-neighbors} should
+be a list of node keys.
+@end defun
+
+@defun get-node graph key
+Retrieve a node from the graph, given its node key.
+
+Returns @code{#f} if no such node exists.
+@end defun
+
+@defun remove-node graph node
+Remvoe @var{node} from @var{graph}, if it exists.
+@end defun
+
+@defun find-dangling-node graph
+Find a node in the graph which no other node ``depends'' on (has an
+edge pointing at it).
+
+NOTE this is O(n^2) (maybe, sort of?)
+Getting it faster would require building an index, which
+is hard since there isn't a total order on symbols.
+@end defun
+
+
+@defun pop-dandling-node graph
+Find a node as per @code{find-dangling-node}, and return two values:
+the node, and a new graph without that node.
+@end defun
+
+@defun resolve-dependency-graph graph
+If each edge is assumed to indicate a nodes dependencies, then this
+procedure will find return a flat list where each dependency is before
+its dependants.
+
+If any link is missing, or a cycle exists, then the result is
+undefined.
+@end defun
diff --git a/doc/ref/general/options.texi b/doc/ref/general/options.texi
new file mode 100644
index 00000000..675e91f3
--- /dev/null
+++ b/doc/ref/general/options.texi
@@ -0,0 +1,32 @@
+@node Getopt-Long Extensions
+@section Getopt-Long extensions
+
+The module @code{(hnh util options)} extend Guile's
+@code{(ice-9 getopt-long)}. The extra keys which can be specified on
+an option are
+
+@table @samp
+@item (description string)
+A propper description of the value. Should be written for human
+consumption.
+
+@item (value value-spec)
+Value is from the core library, but here ...
+@c TODO document me
+@end table
+
+@defun getopt-opt options
+Remove extensions from @var{options}, turning it into a structure
+which can be passed to @code{getopt-long}.
+@end defun
+
+@defun format-arg-help options
+Pretty print an option summary.
+
+Each description will be parsed as XML and then fed through our markup
+system @xref{Markup}.
+@end defun
+
+@defun print-arg-help options [port=(current-error-port)]
+Formats and prints option spec.
+@end defun
diff --git a/doc/ref/introspection.texi b/doc/ref/introspection.texi
new file mode 100644
index 00000000..9c8387d2
--- /dev/null
+++ b/doc/ref/introspection.texi
@@ -0,0 +1,84 @@
+@node Module Introspection
+@chapter Guile Module Introspection
+
+These are various procedures for getting information about modules,
+usually in a static (only looking at ``dead'' source code) way. They
+are currently strewn about a couple files, all under
+@file{hnh/module-introspection}.
+
+TODO rework the file structure.
+
+TODO the all-*-under-directory procedures really need to be
+straightened out.
+
+@defun module-uses* forms
+Find all dependencies of a module by statically analyzing it's source code.
+
+It gives worse resluts than Guile's built in @code{module-uses}, but
+has the benefit that a module which doesn't compile can still be checked.
+
+@var{froms} should be a list gotten by repeateadly calling @code{read}
+on a Scheme source file.
+@end defun
+
+@defun unique-symbols tree
+Return a list of all symbols occuring in @var{tree}. Each symbol is
+noted exactly once, anything which isn't a symbol is discarded.
+@end defun
+
+@defun module-declaration? form
+Checks if @var{form} starts with @code{'define-module}.
+@end defun
+
+@defun find-module-declaration forms
+@anchor{find-module-declaration}
+In a list of forms, find the first one which satisfies @code{module-declarations?}.
+@end defun
+
+@defun get-forms port
+Repeatadly call @code{read} on @var{port}, and return a list of the
+read forms in order of occurence in the file.
+@end defun
+
+@defun all-files-and-modules-under-directory dir
+Like @code{all-modules-under-directory}, but returns 2-lists of
+filename + module name.
+@end defun
+
+@defun all-files-under-directory directory extension
+Return a flat list of all ``regular'' files under @var{directory},
+whose end in @var{extension}.
+
+@example
+(all-files-under-directory "module" ".scm)
+⇒ '("module/hnh/util.scm")
+@end example
+@end defun
+
+@defun all-modules-under-directory directory
+Finds all ``.scm'' files under @var{directory}, and then read them to
+find a module declaration @pref{find-module-declaration}. Returns both
+the list of all the files, as well as all modules found, as a list of
+module lists, each one suitable to be sent to
+@code{reslove-interface}.
+
+Scheme files without a module declaration are not included in the
+result.
+@end defun
+
+@defun fs-find dir
+Find all files under @var{dir}. This includes all file types,
+including directories.
+
+@example
+(fs-find "module")
+;; Would return something on the following form:
+⇒ `(("module/hnh/util.scm" ,(stat "module/hnh/util.scm") regular)
+    ("module/hnh"          ,(stat "module/hnh")          directory)
+    ("module"              ,(stat "module")              directory)
+    ...)
+@end example
+@end defun
+
+@defun module-file-mapping dir
+@end defun
diff --git a/module/hnh/module-introspection/all-modules.scm b/module/hnh/module-introspection/all-modules.scm
index 89ba5dcc..4b224d2f 100644
--- a/module/hnh/module-introspection/all-modules.scm
+++ b/module/hnh/module-introspection/all-modules.scm
@@ -9,7 +9,7 @@
   :export (all-files-and-modules-under-directory
            all-files-under-directory
            all-modules-under-directory
-           fs-find-base fs-find
+           fs-find
            module-file-mapping
            ))
 
-- 
cgit v1.2.3