bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

[Teemu Likonen]

Info nodes

    (emacs) Directory Variables
    (elisp) Directory Local Variables

explain or give examples of function dir-locals-set-directory-class but
neither of them mentions the mandatory third argument MTIME. I quote the
doc string of the function:

    dir-locals-set-directory-class is a compiled Lisp function in
    `files.el'.

    (dir-locals-set-directory-class directory class mtime)

    Declare that the directory root is an instance of class.
    directory is the name of a directory, a string.
    class is the name of a project class, a symbol.
    mtime is either the modification time of the directory-local
    variables file that defined this this class, or nil.

    When a file beneath directory is visited, the mode-specific
    variables from class are applied to the buffer.  The variables
    for a class are defined using `dir-locals-set-class-variables'.

bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

[Teemu Likonen]

On 2009-06-15 19:54 (+0300), Teemu Likonen wrote:

> Info nodes
>
>     (emacs) Directory Variables
>     (elisp) Directory Local Variables
>
> explain or give examples of function dir-locals-set-directory-class but
> neither of them mentions the mandatory third argument MTIME.

It other words if I copy the example from "(emacs) Directory Variables"
and perhaps use my own variables:

    (dir-locals-set-class-variables 'unwritable-directory
      '((nil . ((fill-column . 78)))))

    (dir-locals-set-directory-class
     "/usr/include/" 'unwritable-directory)

I get this:


Debugger entered--Lisp error: (wrong-number-of-arguments #[(directory
class mtime) [...]
[directory class dir-locals-class-alist mtime dir-locals-directory-cache file-name-as-directory expand-file-name error "No such class `%s'" symbol-name] 4 1821511] 2)
  dir-locals-set-directory-class("/usr/include/" unwritable-directory)
  eval((dir-locals-set-directory-class "/usr/include/" (quote unwritable-directory)))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp nil nil)

bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

[Glenn Morris]

Teemu Likonen wrote:

>> Info nodes
>>
>>     (emacs) Directory Variables
>>     (elisp) Directory Local Variables
>>
>> explain or give examples of function dir-locals-set-directory-class but
>> neither of them mentions the mandatory third argument MTIME.
[...]
>     (dir-locals-set-directory-class
>      "/usr/include/" 'unwritable-directory)
[...]
> Debugger entered--Lisp error: (wrong-number-of-arguments #[(directory


Yes, calling a function with the wrong number of arguments causes an error.

The mtime argument is now optional, so there is no error, and no need
to mention the mtime bit in the Emacs manual, IMO. It probably should
be added to the elisp manual.

bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

[Teemu Likonen]

On 2009-06-18 02:58 (-0400), Glenn Morris wrote:

> The mtime argument is now optional, so there is no error, and no need
> to mention the mtime bit in the Emacs manual, IMO.

If I understand the MTIME argument correctly it is (mostly) for Emacs's
internal use to handle .dir-locals.el files. So I agree, now that MTIME
is optional argument it's not necessary to mention it in the Emacs
manual.

> It probably should be added to the elisp manual.

But as you said I think it should be documented in this lower-level
manual.

bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

[Glenn Morris]

Version: 23.3

I documented the mtime argument in the lispref.

bug#3577: 23.0.94; Info manual does not explain MTIME argument for dir-locals-set-directory-class

[Glenn Morris]

Actually my commit appears to be hanging at the moment, but I'll
actually commit it when I am able to.