From 723502e4642b1861b902dd87de59973b3f10eca7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Sun, 10 Sep 2023 21:08:50 +0200
Subject: Clean up and include exception utility documentation.

---
 doc/ref/guile.texi                 |  3 +++
 doc/ref/guile/util-exceptions.texi | 28 +++++++++++++++++++++++-----
 module/hnh/util/exceptions.scm     |  3 +--
 3 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index f32dca65..1fc0065a 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -7,6 +7,7 @@
 @include guile/util.texi
 @include guile/util-path.texi
 @include guile/util-config.texi
+@include guile/util-exceptions.texi
 @include guile/base64.texi
 @include guile/xdg-basedir.texi
 @include guile/web.texi
@@ -24,6 +25,8 @@ Should possibly be replaced by an explicit return-continuation.
 
 @deftp{Error type} warning fmt args
 Thrown when @code{warnings-are-errors} is true.
+
+@ref{warning} for more information.
 @end deftp
 
 @deftp{Error type} max-page page-number
diff --git a/doc/ref/guile/util-exceptions.texi b/doc/ref/guile/util-exceptions.texi
index 4e84d8c4..34ba33f9 100644
--- a/doc/ref/guile/util-exceptions.texi
+++ b/doc/ref/guile/util-exceptions.texi
@@ -1,22 +1,40 @@
-@node Exception Utilities
-@section Exception Utilities
+@node Exception & Warning Utilities
+@section Exception & Warning Utilities
+@anchor{warning}
+
+Warnings are like exceptions, but only fatal when wanted.
+
+@code{(hnh util exceptions)}
 
 @defun warning fmt args ...
+Emit a warning.
 
+If the parameter @var{warnings-are-errors} is true, then an exception
+of type @code{'warning} will be raised, with @var{fmt} and @var{args}
+as arguments.
+
+If that parameter is false, then the procedure in
+@var{warning-handler} will instead be called.
 @end defun
 
 @deftp {parameter} warning-handler
-Procedure, which htnaoe htn oeu htn oeu 
+Parameter containing proceudre which will be called for non-throwing
+warnings. This procedure is assumed by the program to log the warning
+in some way, and continue program flow. But anything goes.
+
+The procedure is given a format specifier (as per Scheme's basic
+@code{format}), along with the correct number of arguments.
 @end deftp
 
 @deftp {parameter} warnings-are-errors
-Boolean parameter
+Boolean parameter, which if set causes warnings to be thrown as exceptions.
 @end deftp
 
 @defun fatal fmt args ...
 Display the message in fmt, populated with args, then raises the UNIX
-signal 2, which kills the program.
+signal SIGINT, which kills the program.
 @end defun
 
 @defun filter-stack pred? stack
+@c TODO document me
 @end defun
diff --git a/module/hnh/util/exceptions.scm b/module/hnh/util/exceptions.scm
index 344eb27a..1c3de8c7 100644
--- a/module/hnh/util/exceptions.scm
+++ b/module/hnh/util/exceptions.scm
@@ -33,8 +33,7 @@
 (define (fatal fmt . args)
   (display (format #f "FATAL: ~?~%" fmt (or args '()))
            (current-error-port))
-  (raise 2)
-  )
+  (raise SIGINT))
 
 
 (define (filter-stack pred? stk)
-- 
cgit v1.2.3