[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#8682: 24.0.50; doc strings of `isearch-mode', `isearch-forward', etc

From: Drew Adams
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"

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]