Ted Zlatanov wrote:
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. */".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?
Admittedly this is a judgment call.
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 ...".PE> -Returns nil on error. PE> +Return nil on error. Is this right? It seems it's talking from the POV of the function.
Attachment:
0001-src-gnutls.c-Restore-some-comments.patch
Description: Text Data