Re: GnuTLS and zeroing keys in Emacs

[Paul Eggert]

Ted Zlatanov wrote:

> PE> -      Lisp_Object cp = listn (CONSTYPE_HEAP, 15,
> PE> -                              /* A symbol representing the cipher */
> PE> -                              intern (gnutls_cipher_get_name (gca)),
>
> You removed the comments from these lists in the C code in several
> places, but I do think they are useful to a reader. Can we keep them?

I restored those particular comments by installing the attached patch. That 
being said, I found the comments to have more cost (in terms of clutter) than 
benefit (in terms of useful information conveyed), and similarly for some nearby 
comments that I also removed. For example, anyone who reads the Emacs C code 
should know that "intern (gnutls_cipher_get_name (gca))" returns a symbol 
representing the cipher name, and the nearby comment "/* A symbol representing 
the GnuTLS cipher. */" just gets in the way; it has the feel of "n++; /* 
Increment N. */".

Admittedly this is a judgment call.

> PE> -Returns nil on error.
> PE> +Return nil on error.
>
> Is this right? It seems it's talking from the POV of the function.

Doc strings for functions should use the imperative form, as it is typically 
shorter and less likely to be misunderstood. For example the doc string for the 
'length' function begins "Return the length of ...".

0001-src-gnutls.c-Restore-some-comments.patch
Description: Text Data