* src/logging/logger.scm (<log-handler>): <#:formatter>: Document the
recently added (v0.2.8) keyword arguments requirement for the formatter
procedure.
Reported-by: Christopher Baines <m...@cbaines.net>
---
Let me know if anything is missing/unclear, Chris. Otherwise I'll
push it in a few days.
src/logging/logger.scm | 21 +++++++++++++++++----
1 file changed, 17 insertions(+), 4 deletions(-)
diff --git a/src/logging/logger.scm b/src/logging/logger.scm
index 8e58f6b..c40c694 100644
--- a/src/logging/logger.scm
+++ b/src/logging/logger.scm
@@ -1,6 +1,6 @@
;; (logging logger) -- write methods to log files
;; Copyright (C) 2003 Richard Todd
-;; Copyright (C) 2024 Maxim Cournoyer <maxim.courno...@gmail.com>
+;; Copyright (C) 2024, 2025 Maxim Cournoyer <maxim.courno...@gmail.com>
;; Copyright (C) 2024 David Pirotte <da...@altosw.be>
;; This program is free software: you can redistribute it and/or modify
@@ -317,9 +317,22 @@ time are:
@table @code
@item #:formatter
-This optional parameter must be a function that takes three arguments:
-the log level, the time (as from @code{current-time}), and the log string
-itself. The function must return a string representing the formatted log.
+
+This optional parameter must be a procedure that takes three
+positional arguments: the log level, the time (as from
+@code{current-time}), and the log string itself. It must also accept
+keyword arguments, preferably with @code{#:allow-other-keys}, so that
+it remains compatible when new keyword arguments are added in the
+future. Currently, two keyword arguments may be populated:
+@table @code
+@item #:source-properties
+Source properties (filename, line, column) association list or #f if
+unavailable.
+@item #:proc-name
+The name (a symbol) of the procedure from which the log was emitted or
+#f if not applicable/unavailable.
+@end table
+The function must return a string representing the formatted log.
Here is an example invocation of the default formatter, and what its
output looks like:
base-commit: cb5ccecbbf06f0f2ba46ce3376c6fad187504bf8
--
2.48.1
