bug#8690: 24.0.50; `declare' doc; conflict with cl-macs.el

bug#8690: 24.0.50; `declare' doc; conflict with cl-macs.el

[Drew Adams]

Emacs has added `declare', choosing to use the same name as the Common
Lisp form.
 
If cl has been loaded, then `C-h f declare' says this:
 
 declare is a Lisp macro in `cl-macs.el'.
 
 (declare &rest SPECS)
 
 Not documented.
 
If cl has not been loaded, then it says this:
 
 declare is a Lisp macro in `subr.el'.
 
 (declare &rest SPECS)
 
 Do not evaluate any arguments and return nil.
 Treated as a declaration when used at the right place in a
 `defmacro' form.  (See Info anchor `(elisp)Definition of declare'.)
 
Something should be done about this.  Perhaps rename the cl form to
avoid the conflict?  Dunno.  But we shouldn't be getting into this kind
of conflict/confusion.  Unless the two are truly compatible, in which
case we should add the same doc string to the macro in cl-macs.el.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-05-16 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'
 

bug#8690: 24.0.50; `declare' doc; conflict with cl-macs.el

[Lars Magne Ingebrigtsen]

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

> Something should be done about this.  Perhaps rename the cl form to
> avoid the conflict?  Dunno.  But we shouldn't be getting into this kind
> of conflict/confusion.  Unless the two are truly compatible, in which
> case we should add the same doc string to the macro in cl-macs.el.

The subr.el definition of `declare' is:

(defmacro declare (&rest _specs)
  "Do not evaluate any arguments and return nil.
Treated as a declaration when used at the right place in a
`defmacro' form.  \(See Info anchor `(elisp)Definition of declare'.)"
  nil)

The cl-macs.el definition is:
  
(defmacro declare (&rest specs)
  (if (cl-compiling-file)
      (while specs
	(if (listp cl-declare-stack) (push (car specs) cl-declare-stack))
	(cl-do-proclaim (pop specs) nil)))
  nil)

So the cl-macs.el version extends the macro, but it's just nil, anyway.

So perhaps the fix here is just to copy over the doc string from the
subr.el version to the cl-macs.el version?
  
-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8690: 24.0.50; `declare' doc; conflict with cl-macs.el

[Lars Magne Ingebrigtsen]

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

> So perhaps the fix here is just to copy over the doc string from the
> subr.el version to the cl-macs.el version?

I wrote a new doc string for the cl-macs.el version.

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

bug#8690: 24.0.50; `declare' doc; conflict with cl-macs.el

[Drew Adams]

> > So perhaps the fix here is just to copy over the doc string from the
> > subr.el version to the cl-macs.el version?
> 
> I wrote a new doc string for the cl-macs.el version.

Hopefully your new doc is _not_ the same as what is in subr.el, unless these two
versions of the macro are in effect the same thing.

It is a bug, if the behaviors are different, to use the same doc.  That makes
things even more confusing.

Any differences between the two macros that affect results or behavior need to
be called out in the doc.  Hopefully you did that (?).

It's unfortunate that Emacs Dev sometimes uses the same names for cl.el stuff
and non-cl.el stuff.  And the addition of `declare' to non-cl Emacs is recent.
Hopefully the macros are identical in effect.  If not then we are introducing
bugs.

But if they are identical, then we should remove the cl.el version altogether,
so I'm guessing that they are not.

bug#8690: 24.0.50; `declare' doc; conflict with cl-macs.el

[Lars Magne Ingebrigtsen]

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

> But if they are identical, then we should remove the cl.el version altogether,
> so I'm guessing that they are not.

They're quite different.

Here's the cl.el doc string:

---
Declare SPECS about the current function while compiling.
For instance

  \(declare (warn 0))

will turn off byte-compile warnings in the function.
---

(If I were dictator, I'd dump Emacs with cl* in the image and get rid of
all these almost-cl functions from subr.el, but that's another long, old
and boring argument.)

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