bug#18069: 24.4.50; doc of rectangle highlighting & redisplay code

bug#18069: 24.4.50; doc of rectangle highlighting & redisplay code

[Drew Adams]

The doc is, well, missing.

Nothing for the advice of `redisplay-(un)highlight-region-function' or
`region-extract-function', or for those variable themselves, or for the
functions used to advise them (`rectangle--highlight-for-redisplay', for
example).

Nothing for `redisplay--update-region-highlight(s)', or other funtions
that use those `*-function' vars, or for `pre-redisplay-function', which
uses `redisplay--update-region-highlight'.

IOW, nothing for anything that does region (un)highlighting redisplay,
including `deactivate-mark' (which has a doc string, but whose doc
string does not cover this new part of its behavior).

None of the so-called "New rectangle integration with kill-ring"
behavior is documented in doc strings.  It is also not documented in
NEWS, AFAICT.

This code change represents a change in user-visible behavior, and it
should be documented.


[It's a shame that Emacs Dev has increasingly neglected to add helpful
 doc strings (IMHO).  The originator of the self-documenting editor is
 no longer watching closely, and developers will be developers, I
 suppose...  Too bad.

 BTW, why is Emacs code simply using `add-function' all over the place
 now, instead of actually adding the code to the functions?  Is advice
 the new normal for Emacs code maintenance?]


In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#18069: 24.4.50; doc of rectangle highlighting & redisplay code

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> None of the so-called "New rectangle integration with kill-ring"
> behavior is documented in doc strings.  It is also not documented in
> NEWS, AFAICT.

Having a doc string on, say, `rectangle--extract-region' to say "extract
the region, but in a rectangular way" doesn't really seem to say more
than the function name itself, so I don't think that'd be helpful.

Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no