Eli Zaretskii <eliz@gnu.org> writes:

>> 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" <bug-gnu-emacs@gnu.org>
>>
>> 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'.

Isn't that kinda redundant? Especially saying port twice doesn't help to
understand the purpose the variable is self explanatory. 

>> +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.

Replaced the second NAME with it.

>> +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?= <bjorn.bidar@thaodan.de>
>> 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.

Done that while doing so I noticed that thghe info manual also needs
updating.
Updated that higlighted that the function updates the current sieve
buffer.