GNU bug report logs - #6525
documentation of macro `with-silent-modifications' 1 typo + multi-horrid

Previous Next

Full log

View this message in rfc822 format

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 6525 <at> debbugs.gnu.org
Subject: bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid
Date: Thu, 01 Jul 2010 03:10:11 +0200

> cosmetic ones, undo data may become corrupted.  Typically used
> ^^^|^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^
> what is non-cosmetic? |             what is an atypical usage?
>                       |
>          why not say `buffer-undo-list'?

Docstrings should generally only document what the function/macro does,
rather than how they're used.  So the "typical uses" I put here is
actually a bad idea, tho it was just easier to do that than to try and
describe what the macro does, especially since it's really the use for
which it's designed.  I don't know what atypical uses might be, and
don't care about them (at least until they come complaining about some
undesirable part of the behavior).

> around modifications of text-properties which do not really affect
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^
>                          what is the affector txt-prop or the mod?

Some other code: the caller would presumably know.

> the buffer's content.
> ^^^^^^^^^^^^^|^^^^^^
>    exactly what _is_ content - chars, tps, overlays, fields, faces?

Can be any of it, depending on the case, because it's a conceptual
notion, rather than a technical one: typically "modify the buffer's
content" means "saving the buffer results in a different file".


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.