GNU bug report logs - #8682
24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.

Previous Next

Full log

View this message in rfc822 format

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 8682 <at> debbugs.gnu.org
Subject: bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc.
Date: Fri, 15 Jul 2011 08:06:06 -0700

> It's an internal function.

"Internal" functions too deserve doc strings, in general.

And nothing in Emacs is truly "internal".  Emacs purposefully documents itself,
at all levels.  That documentation is available to all users interactively.

Skip creating reasonable doc strings and you stab Emacs, the "self-documenting
editor", in the back.

It was only in the Dark Ages, when doc strings were expensive because hardware
was expensive, that we used comments instead of doc strings for many "internal"
functions.

We should not be lazy and cop out wrt "internal" functions.  There is no strict
separation in Emacs (or GNU generally) between users and developers, between
"internal" code and external use of that code.

> The only thing that's useful in that doc string is the thing that's
> already there, and which you want removed:
> 
> > And you can remove this sentence from the doc string - a 
> > function's doc should, in general, not mention callers:
> > "It is called by the function `isearch-forward' and other related
> > functions."

No, that is not "useful".  More importantly, it is generally a bad idea for a
callee to call out who calls it.  There are exceptional cases, but this is not
one.

Previous Next

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