GNU bug report logs - #8098
24.0.50; Doc strings in `image-mode.el'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 8098 in the body.
You can then email your comments to 8098 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; Doc strings in `image-mode.el'
Date: Tue, 22 Feb 2011 13:41:34 -0800

Consider adding more doc strings - there is a paucity of them in this
file.
 
Remove the second line of the `image-type' doc string - we don't
normally document the _use_ of a variable (since it could be used
for more than one thing).
 
Why "as text" in the doc string of `image-minor-mode-map' but not that
of `image-mode-map'?  Is that correct?  Maybe it is, in which case the
minor mode is poorly named.  The names indicate that they are the same
thing, one major the other minor.
 
`image-toggle-display-text' is a _toggle_, so its doc string's first
line should not say that it shows the file as text.  It should say that
it toggles showing the file as text (or some such).  Similarly for
`image-toggle-display-image'?  And `image-toggle-display'?  (It's
unclear from the doc strings what this is all about.  Why three
commands?)
 
Why is this function named `*-hook': `image-after-revert-hook'?  Why not
just `image-after-revert'?  This is not a hook (a variable); it is a
hook function.
 
Doc string of `image-transform-mode' is grammatically incorrect:
"transforming the view of images Image modetransforming the view of
images Image mode".
 
Capitalize and spell-check the doc string of `image-transform-mode'.
And say a bit more (scaling and rotating what?).
 
`image-transform-resize', `image-transform-properties', and
`image-transform-set-resize': Doc string first line is not standalone
(incomplete sentence).

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-02-14 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

Message #8 received at 8098 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8098 <at> debbugs.gnu.org
Subject: Re: bug#8098: 24.0.50; Doc strings in `image-mode.el'
Date: Sat, 09 Apr 2011 16:30:46 -0400

"Drew Adams" <drew.adams <at> oracle.com> writes:

> `image-toggle-display-text' is a _toggle_, so its doc string's first
> line should not say that it shows the file as text.  It should say that
> it toggles showing the file as text (or some such).  Similarly for
> `image-toggle-display-image'?

These functions don't toggle.  They are helper functions for
image-toggle-display and co.

I've cleaned up the other documentation problems you pointed out.
Thanks.

Message #13 received at 8098 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> stupidchicken.com>
Cc: 8098 <at> debbugs.gnu.org
Subject: RE: bug#8098: 24.0.50; Doc strings in `image-mode.el'
Date: Sat, 9 Apr 2011 13:37:06 -0700

> > `image-toggle-display-text' ... `image-toggle-display-image'?
> 
> These functions don't toggle.  They are helper functions for
> image-toggle-display and co.

Oh, right.  OK, but in that case we could have better names for them.  Maybe
consider using Stefan's `*--*' convention for "internal" functions here.  I.e.,
`image-toggle-display--text', `image-toggle-display--image'

> I've cleaned up the other documentation problems you pointed out.

Thx.

Previous Next

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