Indicate both special form and macro in doc

[xiongtx]

Some symbols, like clojure.core/let, are special forms AND macros. cider-doc should indicate this.

[bbatsov]

I'm afraid I don't understand how this can be. Something is either a macro or a special form, can't see how it can be both...

[xiongtx]

Consider clojure.core/let:

user> (meta #'let)
{:added "1.0",
 :ns #namespace[clojure.core],
 :name let,
 :special-form true,
 :file "clojure/core.clj",
 :column 1,
 :line 4325,
 :macro true,
 :arglists ([bindings & body]),
 :doc
 "binding => binding-form init-expr\n\n  Evaluates the exprs in a lexical context in which the symbols in\n  the binding-forms are bound to their respective init-exprs or parts\n  therein.",
 :forms [(let [bindings*] exprs*)]}

Note that :special-form true and :macro true.

The other ones in clojure.core are:

(->> (vals (ns-publics 'clojure.core)) 
     (map meta)
     (filter #(and (:special-form %) (:macro %)))
     (map :name))
     
;; => (let fn letfn loop)      

[bbatsov]

Yeah, I know this, but I just don't understand how is it possible and whether we want to show this to the users. Might be a bit confusing...

@arrdem As a documentation expert what's your take on this?

[arrdem]

So my $0.02 is that let is a macro. Technically it's let* which is the special form (ref. Compiler.java, impl, bootstrap let, destructuring let).

The fact that underneath let is the let* special form which actually establishes bindings is, to me, fairly worthless. let* is a base case, required by the fact that Clojure (and most traditional Lisps) macro systems depend on symbol equality/identity to determine whether to continue macroexpansion or not.

A quick grep of Clojure suggests that ^:special-form is unused except in clojure.repl/doc and friends which can hardly be considered authoritative given the general state of core.

This wasn't done deliberately but it turns out that Grimoire doesn't document let*, just the destructuring let macro we all know and love. Likewise fn*.

Aside: let* is total magic. It doesn't resolve. It isn't namespaced. It only exists in Compiler.java.

[xiongtx]

My view is that the user should be given the information that the developer provides. If let if marked as both macro and special form, that's what should be displayed.

let* is total magic. It doesn't resolve. It isn't namespaced. It only exists in Compiler.java.

Right...that's why it's a special form after all.

[bbatsov]

My view is that the user should be given the information that the developer provides. If let if marked as both macro and special form, that's what should be displayed.

Fair enough. My main concern is that this might be viewed as confusing by some. Especially in light of this document https://clojure.org/reference/special_forms

Anyways, I'm fine with accepting this change, but it needs a changelog entry.

[xiongtx]

Added changelog entry.