bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[MON KEY]

pretests 23.0.92.1 thru 23.0.95

documentation of args to `documentation-property' differ info<-->help&src

C-h f documentation-property
=> "(documentation-property symbol prop &optional raw)"

(info "(elisp)Accessing Documentation")
=>  "-- Function: documentation-property symbol property &optional verbatim"

-----------------------------------------------
../emacs-23.0.95/info/elisp-5  @lines 2258-2261

"24.2 Access to Documentation Strings
====================================

 -- Function: documentation-property symbol property &optional verbatim"

------------------------------------------
../emacs-23.0.95/src/doc.c  @lines 475-476

"  (symbol, prop, raw)
     Lisp_Object symbol, prop, raw;"

bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[Glenn Morris]

MON KEY wrote:

> documentation of args to `documentation-property' differ info<-->help&src
>
> C-h f documentation-property
> => "(documentation-property symbol prop &optional raw)"
>
> (info "(elisp)Accessing Documentation")
> =>  "-- Function: documentation-property symbol property &optional verbatim"

If your point is, they use different names for some of the arguments,
this is of no importance.

bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[MON KEY]

On Thu, Jul 2, 2009 at 10:40 PM, Glenn Morris<rgm@gnu.org> wrote:
>
> If your point is, they use different names for some of the arguments,
> this is of no importance.
>

Blech.

 I have no point other than to indicate that there is a discrepancy.

It is *important* enough that I noticed the discrepancy when trying to
_understand_ what the function does!

The discrepancy - however trivial it  may be to _you_ - is none the
less a discrepancy.

Surely you don't hold this view for _all_ functions.

Should one assume that consistent indication of the args to a function
is of no importance across the board - or does this apply only for
this particular inconsistency?

Some pigs are more equal than others i guess...

s_P

bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[martin rudalics]

 > The discrepancy - however trivial it  may be to _you_ - is none the
 > less a discrepancy.
 >
 > Surely you don't hold this view for _all_ functions.
 >
 > Should one assume that consistent indication of the args to a function
 > is of no importance across the board - or does this apply only for
 > this particular inconsistency?

The current Elisp reference manual features more than 500 such
discrepancies.  Most of them would have to be fixed by changing the
specification, not the manual.  Changing the specification means check
for name clashes, reindent code, refill doc-strings and comments,
recompile, rebuild.  Doing this manually would get people busy for quite
some time.

martin

bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[MON KEY]

On Fri, Jul 3, 2009 at 2:46 AM, martin rudalics<rudalics@gmx.at> wrote:
> The current Elisp reference manual features more than 500 such
> {...}
> recompile, rebuild.  Doing this manually would get people busy for quite
> some time.

Sure, but this particular case is significant in a way that other +/-
499 might not be;
`documentation-property' relates to the documentation of documentation.

Me: "How shall I get at a symbol's documentation?"
Me to myself: "RTFM!"
Me: "Manual doesn't agree with source..."
Me to myself: "Hrmmm... well, FTFM!"

Getting to discrepancies like this one is _kinda_ important.

Again, in this _particular_ situation this is not simply a discrepancy
but a fundamental inconsistency w/re to Emacs.

I understand that this particular situation may pose a bootstrapping
issue. However, if that is the case then it certainly doesn't hold
that the 'discrepancy'  is of "no importance".

What exactly does it say that the one true self documenting editor
can't/won't correctly self document the very documentation of how it
self documents?

Actually - on second thought - disregard the previous rhetorical
question its not of any importance...

> martin
s_P

bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[Glenn Morris]

severity 3740 minor
tags 3740 wontfix
stop

MON KEY wrote:

> Surely you don't hold this view for _all_ functions.

Yep. When one writes a function, one tends to use short variable names
(`prop'), when one documents it in a manual, one might want to use
more descriptive argument names (`properties'). They're just dummy
variables, it doesn't matter to me what they are called.

Processed: Re: bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

[Emacs bug Tracking System]

Processing commands for control@emacsbugs.donarmstrong.com:

> severity 3740 minor
bug#3740: documentation of args to `documentation-property' differ  info<-->docstring on 23.0.92.1 thru 23.0.95
Severity set to `minor' from `normal'

> tags 3740 wontfix
bug#3740: documentation of args to `documentation-property' differ  info<-->docstring on 23.0.92.1 thru 23.0.95
There were no tags set.
Tags added: wontfix

> stop
Stopping processing here.

Please contact me if you need assistance.

Don Armstrong
(administrator, Emacs bugs database)