Macros that are not loaded should be included in cljs analysis

[lread]

Currently

While looking at cljdoc/cljdoc#543 I was reminded that
ClojureScript analysis only includes macros in .clj files if they happen to be loaded by other namespaces in a library.

But...

Since all Clojure macros are available to ClojureScript, all macros should be included under ClojureScript analysis.

But tell me Lee...

What if a library author wanted to exclude a macro from their API?

Well, the macro or macro namespace could be marked with ^:no-doc.

But if a library author wants to include a macro for ClojureScript but not Clojure?
Well, I think one way would be to use reader conditionals in a .cljc file like so:

(ns testing123.macros)

(defmacro cljs-doc-only #?(:clj {:no-doc true}) [x]
  `(println "ho" ~x))

(defmacro clj-doc-only #?(:cljs {:no-doc true}) [x]
  `(println "hey" ~x))

#?(:clj (defmacro clj-code-only [x]
          `(println "foo" ~x))
   :cljs (defmacro cljs-code-only [x]
           `(println "bar" ~x)))

So...

Does this mean we have to always do Clojure analysis to pick up macros in .clj files, even if the user has requested ClojureScript-only analysis?

Maybe. Not sure yet.

[lread]

Afterthoughts

But that clj-code-only macro is useable from ClojureScript:
Here it is exposed for cljs use:

(ns testing123.macros2
  #?(:cljs (:require-macros [testing123.macros2])))

#?(:clj (defmacro clj-code-only [x]
          `(println "foo" ~x)))

So, a macro that is not explicitly exposed in this way for cljs easy-use, would have to be brought in by require-macros, yes?

A thoughtful library author would probably not typically force the user of their library to use require-macros and would expose macros for cljs use as above.

But...

This syntax/technique did not always exist, it was introduced in 2015.

Some very old or naive libraries would still expect their macros to be required the old way. (here's where core.async made the change to support the new syntax).

So...

I'm not so sure about this anymore.

If a macro needs to be brought in by :require-macros (or other equivalent cljs syntaxes), should it be considered part of the cljs API?

And how is a modern cljs developer to know that they need to use a special syntax to bring in the macro?

[lread]

Well, I guess we just can't know the author's intent for macros potentially reachable from cljs. If an author is surprised that their macros are included in the cljs API presented by cljdoc, we do offer a mechanism to exclude them via :no-doc (see above).

So... I think I'll take a stab at including reachable macros in the cljs API.

If an author has requested only cljs analysis we'll not also include the macro under clj analysis.

[lread]

Another option

If the macro is loaded during cljs analysis it is currently included in the cljs analysis.

Perhaps if the macro is not loaded, it should appear under clj analysis only.
This tells cljs user that the macro is available, but must be required using special syntax.
This means that a cljs project should be clj analysis if it wants its non-loaded clj-macros included.

This option implies, other than adding some tests, do nothing.

But...

But can I replicate this for static analysis? (an exploration currently in progress)
Can I determine that a macro has been loaded?