[PATCH 2/2] services: configuration: Show default values of list types.

  • Done
  • quality assurance status badge
Details
2 participants
  • Clément Lassieur
  • Ludovic Courtès
Owner
unassigned
Submitted by
Clément Lassieur
Severity
normal

Debbugs page

C
C
Clément Lassieur wrote on 25 Nov 2017 07:05
(address . guix-patches@gnu.org)
20171125150531.26769-1-clement@lassieur.org
* doc/guix.texi (Messaging Services): Regenerate it.
* gnu/services/configuration.scm (show-default?): Fix recursion.
* gnu/services/messaging.scm (show-default?): Fix recursion.
(prosody-configuration)[modules-enabled]: Remove default value from docstring.
---
doc/guix.texi | 7 +++++--
gnu/services/configuration.scm | 3 ++-
gnu/services/messaging.scm | 6 +++---
3 files changed, 10 insertions(+), 6 deletions(-)

Toggle diff (79 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index a008b1c0a..bd3e1b0f2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -13927,8 +13927,9 @@ Defaults to @samp{#f}.
@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
This is the list of modules Prosody will load on startup. It looks for
@code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
-Documentation on modules can be found at: @url{http://prosody.im/doc/modules}.
-Defaults to @samp{%default-modules-enabled}.
+Documentation on modules can be found at:
+@url{http://prosody.im/doc/modules}.
+Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
@@ -14032,6 +14033,7 @@ Defaults to @samp{#f}.
@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
Set of mechanisms that will never be offered. See
@url{https://prosody.im/doc/modules/mod_saslauth}.
+Defaults to @samp{("DIGEST-MD5")}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
@@ -14199,6 +14201,7 @@ Hostname of the component.
@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
Port(s) Prosody listens on for component connections.
+Defaults to @samp{(5347)}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} string component-interface
diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
index 0a2219e74..c45340f02 100644
--- a/gnu/services/configuration.scm
+++ b/gnu/services/configuration.scm
@@ -1,6 +1,7 @@
;;; GNU Guix --- Functional package management for GNU
;;; Copyright © 2015 Andy Wingo <wingo@igalia.com>
;;; Copyright © 2017 Mathieu Othacehe <m.othacehe@gmail.com>
+;;; Copyright © 2017 Clément Lassieur <clement@lassieur.org>
;;;
;;; This file is part of GNU Guix.
;;;
@@ -165,7 +166,7 @@
(configuration-field-default-value-thunk f)
(lambda _ '%invalid))))
(define (show-default? val)
- (or (string? default) (number? default) (boolean? default)
+ (or (string? val) (number? val) (boolean? val)
(and (symbol? val) (not (eq? val '%invalid)))
(and (list? val) (and-map show-default? val))))
`(deftypevr (% (category
diff --git a/gnu/services/messaging.scm b/gnu/services/messaging.scm
index c75c71585..d57a7562a 100644
--- a/gnu/services/messaging.scm
+++ b/gnu/services/messaging.scm
@@ -354,8 +354,8 @@ Example: @code{(admins '(\"user1@@example.com\" \"user2@@example.net\"))}"
(module-list %default-modules-enabled)
"This is the list of modules Prosody will load on startup. It looks for
@code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
-Documentation on modules can be found at: @url{http://prosody.im/doc/modules}.
-Defaults to @samp{%default-modules-enabled}."
+Documentation on modules can be found at:
+@url{http://prosody.im/doc/modules}."
common)
(modules-disabled
@@ -722,7 +722,7 @@ See also @url{http://prosody.im/doc/modules/mod_muc}."
(display c))
str))))
(define (show-default? val)
- (or (string? default) (number? default) (boolean? default)
+ (or (string? val) (number? val) (boolean? val)
(and (list? val) (and-map show-default? val))))
(format #t "@deftypevr {@code{~a} parameter} ~a ~a\n~a\n"
configuration-name field-type field-name field-docs)
--
2.15.0
L
L
Ludovic Courtès wrote on 26 Nov 2017 08:31
(name . Clément Lassieur)(address . clement@lassieur.org)(address . 29438@debbugs.gnu.org)
87d145vw5z.fsf@gnu.org
Clément Lassieur <clement@lassieur.org> skribis:

Toggle quote (4 lines)
> * doc/guix.texi (Messaging Services): Regenerate it.
> * gnu/services/configuration.scm (show-default?): Fix recursion.
> * gnu/services/messaging.scm (show-default?): Fix recursion.

Rather “Check VAL rather than DEFAULT.”

Toggle quote (2 lines)
> (prosody-configuration)[modules-enabled]: Remove default value from docstring.

LGTM, though I’m afraid we’ll have a hard time keep guix.texi in sync,
at least until we have an automated mechanism to regenerate those bits.

Also, I was thinking that ‘guix system search’ could display
field/default-value pairs. I’m not 100% sure it’s a good idea because
that could be very verbose.

Thoughts?

Ludo’.
C
C
Clément Lassieur wrote on 27 Nov 2017 18:56
control message for bug #29438
(address . control@debbugs.gnu.org)
877eubf6wl.fsf@lassieur.org
tags 29438 fixed
close 29438
C
C
Clément Lassieur wrote on 10 Dec 2017 05:26
Re: [bug#29438] [PATCH 2/2] services: configuration: Show default values of list types.
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 29438@debbugs.gnu.org)
87shciogs0.fsf@lassieur.org
Ludovic Courtès <ludo@gnu.org> writes:

Toggle quote (13 lines)
> Clément Lassieur <clement@lassieur.org> skribis:
>
>> * doc/guix.texi (Messaging Services): Regenerate it.
>> * gnu/services/configuration.scm (show-default?): Fix recursion.
>> * gnu/services/messaging.scm (show-default?): Fix recursion.
>
> Rather “Check VAL rather than DEFAULT.”
>
>> (prosody-configuration)[modules-enabled]: Remove default value from docstring.
>
> LGTM, though I’m afraid we’ll have a hard time keep guix.texi in sync,
> at least until we have an automated mechanism to regenerate those bits.

Thank you for reviewing!

It's a bit sad that most services' docstrings are not in sync with the
.texi file, it would be great to have an automated mechanism to update
the documentation. I use a hackish Emacs snippet to maintain Prosody
documentation, but something like "make generate-documentation
<service>" would be much better. I'll think about it.

Toggle snippet (9 lines)
@c The following documentation was initially generated by
@c (generate-documentation) in (gnu services messaging). Manually maintained
@c documentation is better, so we shouldn't hesitate to edit below as
@c needed. However if the change you want to make to this documentation
@c can be done in an automated way, it's probably easier to change
@c (generate-documentation) than to make it below and have to deal with
@c the churn as Prosody updates.

I don't really agree with this comment that can be found in several
places in our documentation. I believe that when there is a
(generate-documentation) procedure, manual edits shouldn't be
encouraged. But it's probably not worth updating it while there is no
easy way to automatically generate the documentation.

Toggle quote (6 lines)
> Also, I was thinking that ‘guix system search’ could display
> field/default-value pairs. I’m not 100% sure it’s a good idea because
> that could be very verbose.
>
> Thoughts?

It would be verbose indeed, and if people want to have details about
fields and default values, they can search the manual.
L
L
Ludovic Courtès wrote on 10 Dec 2017 06:29
Generating service documentation
(name . Clément Lassieur)(address . clement@lassieur.org)(address . 29438@debbugs.gnu.org)
87zi6qbqrv.fsf_-_@gnu.org
Hi Clément,

Clément Lassieur <clement@lassieur.org> skribis:

Toggle quote (20 lines)
> It's a bit sad that most services' docstrings are not in sync with the
> .texi file, it would be great to have an automated mechanism to update
> the documentation. I use a hackish Emacs snippet to maintain Prosody
> documentation, but something like "make generate-documentation
> <service>" would be much better. I'll think about it.
>
> @c The following documentation was initially generated by
> @c (generate-documentation) in (gnu services messaging). Manually maintained
> @c documentation is better, so we shouldn't hesitate to edit below as
> @c needed. However if the change you want to make to this documentation
> @c can be done in an automated way, it's probably easier to change
> @c (generate-documentation) than to make it below and have to deal with
> @c the churn as Prosody updates.
>
> I don't really agree with this comment that can be found in several
> places in our documentation. I believe that when there is a
> (generate-documentation) procedure, manual edits shouldn't be
> encouraged. But it's probably not worth updating it while there is no
> easy way to automatically generate the documentation.

It’s complicated. Automatically-generated documentation can be useful
as a reference, but it doesn’t really help you get started. It’s
typically a very unfriendly, Javadoc-style, dump of functions/fields.
It think that’s what this comment is about: generated doc is a start,
but it’s not doing much of a service to our users.

Now, if the choice is between terse-and-outdated doc and
terse-but-automatically-updated doc, the latter is preferable. It’s
just not ideal IMO.

Toggle quote (9 lines)
>> Also, I was thinking that ‘guix system search’ could display
>> field/default-value pairs. I’m not 100% sure it’s a good idea because
>> that could be very verbose.
>>
>> Thoughts?
>
> It would be verbose indeed, and if people want to have details about
> fields and default values, they can search the manual.

Yeah. I was thinking that it might be helpful, let’s say if you’re
using openssh-service-type and you don’t remember the exact name of an
option having to do with authentication. Dunno.

Thanks,
Ludo’.
?
Your comment

This issue is archived.

To comment on this conversation send an email to 29438@patchwise.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 29438
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch