bug#19338: [PATCHv2 1/2] descr-text: add `describe-char-eldoc' describing character at point

[Eli Zaretskii <eliz@gnu.org>]

> From: Michal Nazarewicz <mpn@google.com>
> Date: Thu, 11 Dec 2014 17:02:31 +0100
> Cc: 19338@debbugs.gnu.org
> 
> From: Michal Nazarewicz <mina86@mina86.com>
> 
> * lisp/descr-text.el (describe-char-eldoc): New function returning
> basic Unicode codepoint information (e.g. name) about character
> at point.  It is meant to be used as a default value of the
> `eldoc-documentation-function' variable.
> (describe-char-eldoc--format, describe-char-eldoc--truncate):
> New helper functions for `describe-char-eldoc' function.
> 
> * tests/automated/descr-text-test.el: New file with tests for
> `describe-char-eldoc--truncate', `describe-char-eldoc--format',
> and `describe-char-eldoc'.

Thanks.  Allow me a few comments about the documentation parts.

> +(defun describe-char-eldoc--truncate (name width)
> +  "Truncate NAME at white spaces such that it is no longer than WIDTH.
> +
> +If NAME consists of white space only, return an empty string.
> +
> +Otherwise, if NAME consists of a single word (where word is defined as sequence
> +of non-white space characters), return that word even if it's longer than WIDTH.
> +
> +Otherwise, if first word in NAME is longer or equal WIDTH, return that word with
> +ellipsis character (\"…\") appended; this results in a string longer than WIDTH.
> +
> +Otherwise, take as many words from NAME as possible, separating them with
> +a single space character, while not exceeding WIDTH characters length limit.  If
> +not all words fit, append ellipsis character (\"…\") at the end; the ellipsis is
> +counted towards WIDTH."

The lines in this doc string are too long, some of them are longer
than 79 characters, which will overflow the typical line width on a
TTY.

More importantly, this kind of "pseudo-code" description of what
the function does is not the best way of documenting a function.  It
is best to describe it in natural-language terms, and start with the
most general, then go to the corner cases.  Pseudo-code usually forces
you to describe the corner cases first, which is confusing and might
lead the reader to wrong conclusions.  Likewise with minor details,
like the fact that words are separated with a single space: this
should be mentioned only after you describe the main job.

> +          (let ((ellipsis (and (cdr last) "…")))

Btw, will this display OK on a TTY?  Not all TTYs support UTF-8.

> +Full description message has a \"U+<hex>: <name> (<gc>: <general category>)\"
> +format where:
> +- <hex> is a hexadecimal codepoint of the character (zero-padded to at least
> +  four digits),
> +- <name> is name of the character.

We don't use <this style> to describe parameters, we use THIS STYLE.

> +(defun describe-char-eldoc ()
> +  "Returns a description of character at point for use by ElDoc mode.

"Return", not "Returns".

> +If character at point is a printable ASCII character (i.e. codepoint between 32
> +and 127 inclusively), nil is returned.  Otherwise a description formatted by
> +`describe-char-eldoc--format' function is returned taking into account value

Here you suddenly switch to passive tense, which is both longer and
make the sentence more complicated.  Try sticking to active as much as
is practical.

Thanks again for working on this.