* bug#957: 23.0.60; No doc string for Dired functions
@ 2008-09-10 16:16 Drew Adams
2011-07-06 18:27 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2008-09-10 16:16 UTC (permalink / raw)
To: emacs-pretest-bug
There is still no doc string for many useful Dired functions, from
things like `dired-repeat-overlines' to all of the tree Dired
non-interactive functions. At a minimum, the arguments should be
described in a doc string. Even some commands, like `dired-kill-line',
still have no doc.
In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
of 2008-08-29 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#957: 23.0.60; No doc string for Dired functions
2008-09-10 16:16 Drew Adams
@ 2011-07-06 18:27 ` Lars Magne Ingebrigtsen
2011-07-06 19:16 ` Drew Adams
0 siblings, 1 reply; 7+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-06 18:27 UTC (permalink / raw)
To: Drew Adams; +Cc: 957
"Drew Adams" <drew.adams@oracle.com> writes:
> There is still no doc string for many useful Dired functions, from
> things like `dired-repeat-overlines' to all of the tree Dired
> non-interactive functions. At a minimum, the arguments should be
> described in a doc string. Even some commands, like `dired-kill-line',
> still have no doc.
I've added a doc to `dired-kill-line', but I don't know what
`dired-repeat-overlines' is...
And the noninteractive functions don't need doc strings, really, do
they?
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#957: 23.0.60; No doc string for Dired functions
2011-07-06 18:27 ` Lars Magne Ingebrigtsen
@ 2011-07-06 19:16 ` Drew Adams
2011-07-07 16:30 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2011-07-06 19:16 UTC (permalink / raw)
To: 'Lars Magne Ingebrigtsen'; +Cc: 957
> > There is still no doc string for many useful Dired functions, from
> > things like `dired-repeat-overlines' to all of the tree Dired
> > non-interactive functions. At a minimum, the arguments should be
> > described in a doc string. Even some commands, like
> > `dired-kill-line', still have no doc.
>
> I've added a doc to `dired-kill-line'
Thank you.
> but I don't know what `dired-repeat-overlines' is...
All the more reason for it to get a doc string!
You don't know what it is, but _it_ should know what it is and be able to tell
us. Someone (TM) will need to figure that out and give it a little help in the
self-explanation department.
> And the noninteractive functions don't need doc strings,
> really, do they?
Sure they do, in general. Since when do we document only commands?
In the Dark Ages, doc strings were relatively more expensive (disk, memory,
etc.), and some minor functions were handled with only a comment. Nowadays
there is rarely a good reason not to provide a doc string.
Emacs is the self-documenting editor. If you must access the source code just
to get a description of a function from comments, or worse, to parse uncommented
code to figure out what a function does, then Emacs is not doing its
self-documenting job well.
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#957: 23.0.60; No doc string for Dired functions
2011-07-06 19:16 ` Drew Adams
@ 2011-07-07 16:30 ` Lars Magne Ingebrigtsen
2011-07-07 16:43 ` Drew Adams
0 siblings, 1 reply; 7+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-07 16:30 UTC (permalink / raw)
To: Drew Adams; +Cc: 957
"Drew Adams" <drew.adams@oracle.com> writes:
>> but I don't know what `dired-repeat-overlines' is...
>
> All the more reason for it to get a doc string!
I meant that I couldn't find it. :-) But grepping for
`dired-repeat-over-lines' found it for me.
It, too, is an internal function, and I don't think it's worth
documenting all these. They are only useful if you're doing dired
development, and then you presumably have the sources and can look at
the comments.
> Sure they do, in general. Since when do we document only commands?
>
> In the Dark Ages, doc strings were relatively more expensive (disk, memory,
> etc.), and some minor functions were handled with only a comment. Nowadays
> there is rarely a good reason not to provide a doc string.
I agree, but adding doc strings to purely internal functions that are
presumably self-explanatory to people who need to use them to develop
isn't all that useful.
It's not that I'm against adding doc strings (if somebody feels like
doing that), but it's not, in my opinion worth the time. So I'm closing
this report.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2011-07-07 16:48 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <mailman.18915.1221064059.18990.bug-gnu-emacs@gnu.org>
2008-09-11 20:55 ` bug#957: 23.0.60; No doc string for Dired functions Roland Winkler
2008-09-10 16:16 Drew Adams
2011-07-06 18:27 ` Lars Magne Ingebrigtsen
2011-07-06 19:16 ` Drew Adams
2011-07-07 16:30 ` Lars Magne Ingebrigtsen
2011-07-07 16:43 ` Drew Adams
2011-07-07 16:48 ` Lars Magne Ingebrigtsen
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.