Fork me on GitHub

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 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.

Cora (she/her)23:07:24

so does this mean that both MyRecord and MyType would appear nowhere in the docs?


Yeah, but I think Sean’s observations make good sense here and it should be OK.

Cora (she/her)03:07:40

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


Thanks, yeah, we could maybe figure out something different at some future date.


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...