* 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
[not found] <mailman.18915.1221064059.18990.bug-gnu-emacs@gnu.org>
@ 2008-09-11 20:55 ` Roland Winkler
0 siblings, 0 replies; 7+ messages in thread
From: Roland Winkler @ 2008-09-11 20:55 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 had promised to look into that. I am sorry for the delay.
Roland
^ 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
* bug#957: 23.0.60; No doc string for Dired functions
2011-07-07 16:30 ` Lars Magne Ingebrigtsen
@ 2011-07-07 16:43 ` Drew Adams
2011-07-07 16:48 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2011-07-07 16:43 UTC (permalink / raw
To: 'Lars Magne Ingebrigtsen'; +Cc: 957
> 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.
Leave it open, if you're not against someone adding the doc strings.
Just because you don't have the time or aren't interested in adding the doc
strings does not mean that the bug should be closed.
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#957: 23.0.60; No doc string for Dired functions
2011-07-07 16:43 ` Drew Adams
@ 2011-07-07 16:48 ` Lars Magne Ingebrigtsen
0 siblings, 0 replies; 7+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-07 16:48 UTC (permalink / raw
To: Drew Adams; +Cc: 957
"Drew Adams" <drew.adams@oracle.com> writes:
> Just because you don't have the time or aren't interested in adding the doc
> strings does not mean that the bug should be closed.
It is my opinion that doc strings will not be added to the internal
functions of dired.el through being unclosed in this bug tracker.
--
(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.