bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#22336: 25.0.50; cl-generic.el features are not documented in ELisp m


From: Eli Zaretskii
Subject: bug#22336: 25.0.50; cl-generic.el features are not documented in ELisp manual
Date: Sat, 23 Jan 2016 14:51:36 +0200

> Cc: 22336@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 23 Jan 2016 11:20:03 +0300
> 
> On 01/23/2016 09:06 AM, Eli Zaretskii wrote:
> 
> > Note that the doc strings don't tell everything I wrote, and sometimes
> > seem to say inaccurate or even contradictory things, so if what I
> > wrote correctly describes what the implementation actually does, the
> > doc strings (as well as some of the comments) in cl-generic.el should
> > probably be brought in line with the reality.
> 
> Could you give an example of them being wrong?

  (defmacro cl-defgeneric (name args &rest options-and-methods)
    "Create a generic function NAME.
  DOC-STRING is the base documentation for this class.  A generic
  function has no body, as its purpose is to decide which method body
  is appropriate to use.  Specific methods are defined with `cl-defmethod'.
  With this implementation the ARGS are currently ignored.
  OPTIONS-AND-METHODS currently understands:
  - (:documentation DOCSTRING)
  - (declare DECLARATIONS)
  - (:argument-precedence-order &rest ARGS)
  - (:method [QUALIFIERS...] ARGS &rest BODY)
  BODY, if present, is used as the body of a default method.

  \(fn NAME ARGS [DOC-STRING] [OPTIONS-AND-METHODS...] &rest BODY)"

It says a generic function has no body, but the usage info does
mention body, and the last part of the doc string says BODY if present
is used as the default method.  Or is that the body of :method?
Anyway, specific methods can evidently be defined by cl-defgeneric as
well, whereas the doc string says they should be defined by
cl-defmethod.  The semantics of :method is never described at all (and
I saw no examples of its usage to inspire me, AFAIR).

  (defmacro cl-defmethod (name args &rest body)
    "Define a new method for generic function NAME.
  I.e. it defines the implementation of NAME to use for invocations where the
  value of the dispatch argument matches the specified TYPE.
  The dispatch argument has to be one of the mandatory arguments, and
  all methods of NAME have to use the same argument for dispatch.
  The dispatch argument and TYPE are specified in ARGS where the corresponding
  formal argument appears as (VAR TYPE) rather than just VAR.

  The optional second argument QUALIFIER is a specifier that
  modifies how the method is combined with other methods, including:
     :before  - Method will be called before the primary
     :after   - Method will be called after the primary
     :around  - Method will be called around everything else
  The absence of QUALIFIER means this is a \"primary\" method.

  Other than a type, TYPE can also be of the form `(eql VAL)' in
  which case this method will be invoked when the argument is `eql' to VAL.

  \(fn NAME [QUALIFIER] ARGS &rest [DOCSTRING] BODY)"

"_The_ dispatch argument", in singular means only one such argument is
possible, which is of course false.  The &context dispatch has a
slightly different syntax, but it isn't mentioned here at all, which
makes the description of (VAR TYPE) incorrect in that case.

>                                           I only things omitted in 
> docstrings (but which can be inferred from the commentary, such as 
> dispatch on types such as integer, string, and so on).

Some omissions are very hard to restore.  The most striking example is
TYPE, about which the doc string says nothing at all, and the
commentary says just "plain old types".  How could you arrive at the
long list that's now in the manual, let alone the type hierarchy that
goes with it, except by reading the sources?

As another example, the ":extra STRING" feature is mentioned, but
without any details; I couldn't understand how to use it in practice
(it is not used in the tests, either).

And I don't recommend believing the commentary too much, either.
E.g., what it says about &context in several places is contradictory:

  ;;   E.g. (foo &context (major-mode (eql c-mode))) is an arglist specifying
  ;;   that this method will only be applicable when `major-mode' has value
  ;;   `c-mode'.

and then:

  ;; - then define a context-rewriter so you can write
  ;;   "&context (major-mode c-mode)" rather than
  ;;   "&context (major-mode (derived-mode c-mode))".

and even

  ;; TODO:
  ;;
  ;; - A way to dispatch on the context (e.g. the major-mode, some global
  ;;   variable, you name it).

which makes you think it isn't even implemented...  Also, there's
something about derived-mode there, but it's so contrived and devoid
of examples, that I didn't even put that in the manual.

There were others I was only too happy to forget.  I needed to read
the CLOS documentation to make sense of some things.  Of course,
cl-generic.el doesn't implement all of CLOS, and then adds extension
that are not in CLOS, so even CLOS documentation only helps up to a
point.





reply via email to

[Prev in Thread] Current Thread [Next in Thread]