bug#1144: 23.0.60; No doc string for `symbol-at-point' and other, similar functions

bug#1144: 23.0.60; No doc string for `symbol-at-point' and other, similar functions

[Drew Adams]

Subject line says it all. Please add doc strings. Particularly for
`symbol-at-point', which returns a symbol, not a string.
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-10-03 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#1144: marked as done (23.0.60; No doc string for `symbol-at-point' and other, similar functions)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 908 bytes --]


Your message dated Wed, 22 Oct 2008 16:50:43 -0400
with message-id <87ljwgbbh8.fsf@cyd.mit.edu>
and subject line Re: 23.0.60; No doc string for `symbol-at-point' and other, similar functions
has caused the Emacs bug report #1144,
regarding 23.0.60; No doc string for `symbol-at-point' and other, similar functions
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact don@donarmstrong.com
immediately.)


-- 
1144: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=1144
Emacs Bug Tracking System
Contact don@donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 2915 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.60; No doc string for `symbol-at-point' and other, similar functions
Date: Sat, 11 Oct 2008 14:56:21 -0700
Message-ID: <000e01c92bec$32d29eb0$0200a8c0@us.oracle.com>

Subject line says it all. Please add doc strings. Particularly for
`symbol-at-point', which returns a symbol, not a string.
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-10-03 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'
 




[-- Attachment #3: Type: message/rfc822, Size: 989 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: 1144-done@emacsbugs.donarmstrong.com
Subject: Re: 23.0.60; No doc string for `symbol-at-point' and other, similar functions
Date: Wed, 22 Oct 2008 16:50:43 -0400
Message-ID: <87ljwgbbh8.fsf@cyd.mit.edu>

Done.

bug#1144: closed by Chong Yidong <cyd@stupidchicken.com> (Re: 23.0.60; No doc string for `symbol-at-point' and other, similar functions)

[Drew Adams]

Trying again, after trying to unarchive.

> -----Original Message-----
> From: Drew Adams Sent: Sunday, April 05, 2009 8:37 PM
>
> Must I send a separate bug for each such function? I thought 
> when your complete response was "Done" that you had taken 
> care of all such functions.
> 
> The following functions are all in the same boat. They are 
> all functions for which users will want to see the doc.
> 
> beginning-of-thing
> end-of-thing
> in-string-p
> end-of-sexp
> beginning-of-sexp
> thing-at-point-bounds-of-url-at-point
> forward-whitespace
> forward-symbol
> forward-same-syntax
> word-at-point
> sentence-at-point
> form-at-point

bug#1144: closed by Chong Yidong <cyd@stupidchicken.com> (Re: 23.0.60; No doc string for `symbol-at-point' and other, similar functions)

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Trying again, after trying to unarchive.
>
>> -----Original Message-----
>> From: Drew Adams Sent: Sunday, April 05, 2009 8:37 PM
>>
>> Must I send a separate bug for each such function? I thought 
>> when your complete response was "Done" that you had taken 
>> care of all such functions.
>> 
>> The following functions are all in the same boat. They are 
>> all functions for which users will want to see the doc.
>> 
>> beginning-of-thing
>> end-of-thing
>> in-string-p
>> end-of-sexp
>> beginning-of-sexp
>> thing-at-point-bounds-of-url-at-point
>> forward-whitespace
>> forward-symbol
>> forward-same-syntax
>> word-at-point
>> sentence-at-point
>> form-at-point

No, Chong added documentation to the autoloaded, "external" functions,
but not the purely internal thingatpt functions.  And I think that's the
right decision.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#1144: closed by Chong Yidong <cyd@stupidchicken.com> (Re: 23.0.60; No doc string for `symbol-at-point' and other, similar functions)

[Drew Adams]

> >> Must I send a separate bug for each such function? I thought 
> >> when your complete response was "Done" that you had taken 
> >> care of all such functions.
> >> 
> >> The following functions are all in the same boat. They are 
> >> all functions for which users will want to see the doc.
> >> 
> >> beginning-of-thing
> >> end-of-thing
> >> in-string-p
> >> end-of-sexp
> >> beginning-of-sexp
> >> thing-at-point-bounds-of-url-at-point
> >> forward-whitespace
> >> forward-symbol
> >> forward-same-syntax
> >> word-at-point
> >> sentence-at-point
> >> form-at-point
> 
> No, Chong added documentation to the autoloaded, "external" functions,
> but not the purely internal thingatpt functions.  And I think 
> that's the right decision.

No, it's not the right thing.  Emacs users include Emacs-Lisp users.  Users of
thingatpt.el, in particular, are mainly Emacs-Lisp users.

Whether to document something has nothing to do with whether it is a command or
is autoloaded.  That is, those predicates do not at all suffice to determine
whether something should be documented.

And for Emacs there really is no such thing as an "internal" function.  Yes, we
need not document every function or variable, and yes, some functions and
variables we generally do not expect users to fiddle with.  But Emacs is 100%
open, and it should document itself, as originally intended.

bug#1144: closed by Chong Yidong <cyd@stupidchicken.com> (Re: 23.0.60; No doc string for `symbol-at-point' and other, similar functions)

[Chong Yidong]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

>>> The following functions are all in the same boat. They are all
>>> functions for which users will want to see the doc.

I added the other doc strings.  Closing again.