Using clj-kondo v2023.05.26, given a little bb script alana.clj

(ns alana
  (:require [babashka.process :as p]
            [clojure.edn :as edn]
            [clojure.pprint :as pprint]))

(let [code (first *command-line-args*)
      config {:config-paths ^:replace []
              :analysis {:var-definitions {:meta true}
                         :arglists true}
              :output {:format :edn}}]
  (-> (p/shell {:in code
                :continue true
                :out :string}
               "clj-kondo"
               "--config" (binding [*print-meta* true] (pr-str config))
               "--lint" "-")
      :out
      edn/read-string
      :analysis :var-definitions
      pprint/pprint))

❯ bb alana.clj '(defn foo [x])'                     
var analysis for code: (defn foo [x])
[{:fixed-arities #{1},
  :end-row 1,
  :meta nil,
  :name-end-col 10,
  :name-end-row 1,
  :name-row 1,
  :ns user,
  :name foo,
  :defined-by clojure.core/defn,
  :filename "<stdin>",
  :col 1,
  :name-col 7,
  :defined-by->lint-as clojure.core/defn,
  :end-col 15,
  :arglist-strs ["[x]"],
  :row 1}]

❯ bb alana.clj $'(defn foo {:arglists \'([y])} [x])'
var analysis for code: (defn foo {:arglists '([y])} [x])
[{:fixed-arities #{1},
  :end-row 1,
  :meta {:arglists '([y])},
  :name-end-col 10,
  :name-end-row 1,
  :name-row 1,
  :ns user,
  :name foo,
  :defined-by clojure.core/defn,
  :filename "<stdin>",
  :col 1,
  :name-col 7,
  :defined-by->lint-as clojure.core/defn,
  :end-col 34,
  :arglist-strs ["[x]"],
  :row 1}]

I see, a lotta words without a question.... Apologies @U04V15CAJ, so the question is, I suppose, should arglists overridden by metadata be applied to :arglist-strs?

I think arglists-strs is how the arglist is written and metadata contains additional arglist if supplied as meta?

with :meta [:arglists] you'll get that, I think

$ clj-kondo --lint /tmp/arg.clj --config "{:analysis {:var-definitions {:meta [:arglists]}} :output {:format :edn}}" | jet -t ':analysis :var-definitions'
[{:col 1,
  :defined-by clojure.core/defn,
  :defined-by->lint-as clojure.core/defn,
  :end-col 5,
  :end-row 4,
  :filename "/tmp/arg.clj",
  :fixed-arities #{1},
  :meta {:arglists (quote [y])},
  :name foo,
  :name-col 7,
  :name-end-col 10,
  :name-end-row 1,
  :name-row 1,
  :ns user,
  :row 1}]

@UE21H2HHD I'm doing this in quickdoc: https://github.com/borkdude/quickdoc/blob/db61b35b613d3c1a7e84ea96efab6827cca20406/src/quickdoc/impl.clj#L109-L114

Thanks @U04V15CAJ, so the behaviour is as intended. That works for me. Just wondered if I had found something that was unintended.

yeah, intended, so you can access both values if necessary

Thanks, that makes sense. Do you remember why you decided to go with :arglist-strs instead of :arglists ? I'm guessing that the string encoding helped to avoid forms that might not be edn-readable?

yeah don't exactly remember, I think this was something that clojure-lsp needed

Like for odd stuff: (defn foo [{:keys [:bar :baz] :or {bar #"regex"}}]) :arglist-strs preserves all just fine: ["[{:keys [:bar :baz] :or {bar #\"regex\"}}]"] But if we have same as meta: (defn foo {:arglists '([{:keys [:bar :baz] :or {bar #"regex"}}])} [x]) :meta :arglists is a bit off: ([{:or {bar (re-pattern "regex")}, :keys [:bar :baz]}]) I suppose this is pretty edge-casey.

right, I think arglists-strs is for showing and maybe it makes sense to override it from meta

we could change that I think

What do you think @UKFSJSM38?

:arglists treatment different from :doc . For :doc we always see :doc overridden by metadata in root var map. But for :doc , unlike :arglists , an original value is never interesting.

Yes, it's only for showing in clojure-lsp if one hover or ask the docs of a function that has the arglists meta, so it would work as well for lsp

ok, let's do it then

this would also simplify quickdoc

Just let me know when you do as it will require minor changes in LSP

So is original (un-overridden value) of :arglists ever interesting tho? (It isn't for my use case).

for LSP it is, as it checks for the meta arglists, if not present, use the root arglists-strs

it is only for clj-kondo to deduce the arities, but I don't think clj-kondo makes use of that API

Oh is there other arglists besides the arglists-strs in the root?

@UKFSJSM38 I think what you are using arglist-strs for is just for showing info, you're never interested in the "original", e.g. if a user writes:

(defn foo {:arglists '([x y z])} [& xs])

I think so, let me double check

@U04V15CAJ, I assume arities are deduced from ([x y z]) and not [& xs] , amiright?

Confirmed @U04V15CAJ, you are correct

@UE21H2HHD no, :arglists metadata can't be trusted for arities

It:s not only hover info, but completion, call hierarchy, signature help and other features, but all to present info only

it often uses informal notation like '([xs* xs?)] which is garbage for deducing arity info

yeah, that makes sense, tx

arglists overrides are only to describe usage for docs then, is that right?

So I can write up an issue @U04V15CAJ, but in a nutshell :arglist-strs should be overriden by any :arglists metadata. Zat the idea?

yep!

thanks for bringing this up, I might have just worked around the issue in the past

Very nice discussion, always a pleasure to work with @U04V15CAJ and @UKFSJSM38!

> no, :arglists metadata can't be trusted for arities @U04V15CAJ can :arities metadata be trusted for arities of def's?

(def ^{:arities #{1 2}} f ...)

I've never seen that

yes, there is only :inline-arities metadata in use but I wish to be able to say kondo about arities for functions defined via def so we could utilize :arities similar to :inline-arities

why not write a defn with the right arities then?

Some occurrences in the wild: https://grep.app/search?q=def%20%5E%7B%3Aarglist

why to write defn in case of

(def f another-ns/f)

@UE21H2HHD These are :arglists, not :arities - you weren't reacting to arities I guess?

ooopsie, misread. ignore.

also there is defmulti which I can document only via :arglists

so :arglists metadata works fine for documenting defs and defmultia (and other macros which generates global functions) but unfortunately kondo don't check arities in these case what is sad 🙂

@U0HJNJWJH it would cause false positives which is even sadder

I guess clj-kondo could do a best effort attempt: if arglists only has regular symbols and not * or ? in the name, try to deduce arity info from it. But why the hassle, just define a wrapper function with a proper docstring + arglist using defn : this is what I do in my own libs, tools.build also does it, etc

> it would cause false positives which is even sadder that's why I offer some specific way to say correct data to kondo like :arities

that works for code you own, but not for code you don't own, like clojure.core, etc

> define a wrapper function this sounds suboptimal for me, to generate new java class and add level of indirection just for documentation purpose 🙂 I'll better live without arity check from kondo side

if you avoid writing a function because you'll save a Java class, you're optimizing for the wrong thing in a functional language like Clojure if you ask me ;)

for defmulti the wrapper can be not intended...

true

(phew, agreed in something) 🙂

I've been pondering a different solution for the above problem. If you write:

(def foo impl/foo)

let's narrow to defmulti case do you see a way to define multi-fn and teach kondo about it's arity?

well, maybe kondo can inherit the arity information from dispatch function as well?

it is this issue: https://github.com/clj-kondo/clj-kondo/issues/412 feel free to comment + upvote

I mean, not about defmulti, just the (def foo iml/foo), you posted other stuff while I was searching this issue

upvoted as 3rd one 🙂

other of defmulti there are other ways to define functions using various macros so I don't mind to have clj-kondo specific way to provide arity information for linting any global vars (dynamic, declared in advance...), like #_:clj-kondo/arity ... etc.

I tend to have universal way, not just smart inheritance or similar But inheritance is good as well 🙂

what is smart inheritance?

smart inheritance is in https://github.com/clj-kondo/clj-kondo/issues/412

I've also thought about a reader conditional for clj-kondo so you can specify what code clj-kondo should analyze instead of other code, or so. I'll keep thinking about it, thanks for your input

@U04V15CAJ, @UKFSJSM38 issue raised: https://github.com/clj-kondo/clj-kondo/issues/2096, I look forward to your review and feedback.

ah yes, I forgot that the :arglists is something that is evaluated and there often quoted. so presenting it as is maybe doesn't make sense :-S

Yeah, we'd need to un-quote for :arglist-strs https://github.com/borkdude/quickdoc/blob/db61b35b613d3c1a7e84ea96efab6827cca20406/src/quickdoc/impl.clj#L109-L114

I think this might be the reason that things are the way they are since it's not guaranteed that the expression is parse-able or representable as something useful

since it has to be evaluated first