bug#957: 23.0.60; No doc string for Dired functions

bug#957: 23.0.60; No doc string for Dired functions

[Drew Adams]

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'
 

bug#957: 23.0.60; No doc string for Dired functions

[Lars Magne Ingebrigtsen]

"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/

bug#957: 23.0.60; No doc string for Dired functions

[Drew Adams]

> > 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.

bug#957: 23.0.60; No doc string for Dired functions

[Lars Magne Ingebrigtsen]

"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/

bug#957: 23.0.60; No doc string for Dired functions

[Drew Adams]

> 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.

bug#957: 23.0.60; No doc string for Dired functions

[Lars Magne Ingebrigtsen]

"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/

bug#957: 23.0.60; No doc string for Dired functions

[Roland Winkler]

"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