This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2022-07-28
Channels
- # asami (1)
- # aws (9)
- # babashka (16)
- # beginners (32)
- # calva (2)
- # clj-kondo (20)
- # cljdoc (6)
- # clojure (35)
- # clojure-dev (25)
- # clojure-europe (11)
- # clojure-india (1)
- # clojure-norway (2)
- # clojure-spec (26)
- # clojure-uk (1)
- # clojurescript (41)
- # conjure (3)
- # css (9)
- # cursive (18)
- # data-oriented-programming (6)
- # data-science (2)
- # emacs (47)
- # events (1)
- # fulcro (15)
- # graalvm (30)
- # gratitude (7)
- # honeysql (27)
- # inf-clojure (4)
- # introduce-yourself (2)
- # lsp (129)
- # malli (7)
- # missionary (21)
- # nbb (17)
- # off-topic (18)
- # re-frame (6)
- # releases (1)
- # shadow-cljs (120)
- # vim (7)
- # xtdb (15)
Any opinions on this would be greatly appreciated:
For defrecord MyRecord
, cljdoc is currently always excluding the generated map and positional factory fns, (an old codox default behaviour) nobody has complained yet, so this seems ok (squeek or squawk if you disagree).
But cljdoc is including a MyRecord
item. Way back when, I think it was me who noticed this item was present from the analyzer on the ClojureScript side and so I had cljdoc infer it for the Clojure side (it is not returned by ns-publics
).
While digging https://github.com/cljdoc/cljdoc/issues/444 I have noticed a similar behaviour for deftype MyType
.
ClojureScript analyzer includes MyType
, Clojure ns-publics
return does not.
(The generated positional factory fn for deftype
for both Clojure and ClojureScript is excluded by cljdoc).
I’m thinking, for consistency, both MyRecord
and MyType
should NOT be included in API docs.
Thoughts? If I don’t hear anything back here within the next day or two, I’ll go ahead and make it so.
so does this mean that both MyRecord and MyType would appear nowhere in the docs?
I feel like we could take it a step further and add special support for documenting deftype and defrecord but yeah Sean has the right of it as a way to fix this problem for now
Since you can't attach docstrings to records (or types), nothing shows up in the (ns api) docs except the name which is... of minimal value... and you can't make a record (or type) "private" so there's no way for readers (of cljdoc) to determine whether such a record (or type) is actually useful or even intended to be part of the (public) API. So I'd be perfectly happy with them disappearing from the API docs -- and if they are important to library maintainers, they can add notes to the docs articles and/or the ns
docstring.
There are a couple of these in next.jdbc.result-set
which I would want to suppress if I had the option...