Subject: Re: bug#75956: Various improvements to sieve.el

From: Eli Zaretskii <[email-masked]>
Date: Sat, 08 Feb 2025 11:56:18 +0200

> Date: Fri, 31 Jan 2025 03:54:11 +0200
> From:  Björn Bidar via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> I noticed it is not possible to specific the sieve-manage port when
> calling `sieve-manage`. While fixing that I noticed various other issues.
> - Missing documentation strings on many functions
> - There is function to refresh the buffer but it is not bound
> 
> The attached patches try to fix these issues.

Thanks, please see some comments below.

>  (defun sieve-manage (server &optional port)
> -  (interactive "sServer: ")
> +  "Open ManageSieve SERVER.
> +Optionally with PORT.

This is too cryptic.  It should be something like

  Optional argument PORT specifies the port to use; it defaults to
  `sieve-manage-default-port'.

> +When called in interactively prompt for SERVER:PORT
               ^^              ^
This "in" is redundant.  And a comma is missing after "interactively".

> +if :PORT is not specified fallback to `sieve-manage-default-port'."
                             ^^^^^^^^
"fall back", as two words.

>  (defun sieve-upload (&optional name)
> +  "Upload to script NAME to currently opened server.
             ^^
That "to" should be removed.

> +If NAME is nil detect name from script buffer name;
                 ^
Comma missing.  Also, "name" should be "NAME".  And the semicolon at
the end should be a period.

> +If no open sieve buffer exists call `sieve-manage' first."
                                 ^
Comma missing.

>  (defun sieve-upload-and-bury (&optional name)
> +  "Upload script NAME and bury buffer."

This should say "bury the current buffer", not just "bury buffer".

>  ;;;###autoload
>  (defun sieve-upload-and-kill (&optional name)
> +  "Upload script NAME and kill buffer."

Likewise.

> >From 4c5a9c6267989d888b0b8aaa4a5b91508cd62d6e Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Bj=C3=B6rn=20Bidar?= <[email-masked]>
> Date: Fri, 31 Jan 2025 03:24:44 +0200
> Subject: [PATCH 3/3] * lisp/net/sieve.el: Bind sieve-refresh-scriptlist to
>  refresh buffer
> 
> (sieve-manage-mode-map: Bind `sieve-refersh-scriptlist' to 'g' to refresh
> buffer.
> ---
>  lisp/net/sieve.el | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
> index cd7053a7e65..98f1832d58d 100644
> --- a/lisp/net/sieve.el
> +++ b/lisp/net/sieve.el
> @@ -111,6 +111,7 @@ sieve-manage-mode-map
>    ;; various
>    "?"      #'sieve-help
>    "h"      #'sieve-help
> +  "g"      #'sieve-refresh-scriptlist
>    ;; activating
>    "m"      #'sieve-activate
>    "u"      #'sieve-deactivate
> -- 

This needs a NEWS entry about the new binding.