This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2023-09-07
Channels
- # architecture (35)
- # babashka (9)
- # beginners (31)
- # biff (15)
- # calva (8)
- # catalyst (3)
- # cider (7)
- # clerk (4)
- # clj-kondo (24)
- # clj-yaml (10)
- # clojure (58)
- # clojure-europe (65)
- # clojure-japan (1)
- # clojure-nl (1)
- # clojure-norway (89)
- # clojure-spec (1)
- # clojure-sweden (1)
- # clojure-uk (8)
- # clojurescript (14)
- # cursive (3)
- # datahike (1)
- # datomic (29)
- # emacs (8)
- # graalvm (20)
- # graphql (1)
- # gratitude (2)
- # helix (6)
- # hyperfiddle (65)
- # jobs-discuss (7)
- # leiningen (1)
- # lsp (6)
- # malli (14)
- # missionary (12)
- # nrepl (8)
- # off-topic (24)
- # polylith (29)
- # reagent (14)
- # sci (14)
- # shadow-cljs (6)
- # spacemacs (10)
- # sql (4)
it is unfortunate that a multi-arity defn
cannot take separate docstrings for each arity 😞
I guess if a function does different things depending on the arity, then they should be different functions, with different names
who is the audience of the docstring?
different docs for each arity would probably require a different way to store the docstring:
(defn myfn
"Myfun docstring"
[])
(:doc (meta #'myfn))
;; => "Myfun docstring"
> who is the audience of the docstring? the function users
so documentation for implementors should just co in comments?
for the developer of the function, which are going to be looking at the code, you normally use clojure comments with ; yeah
the nice thing about doc strings is they can be queried by tooling, and from the repl, without having to look at the code, to help the user with what the fn does, how to call it and what to expect as the return
it would be nice if apropos
also searched in doc strings
oh, nice
oh but find-doc
doesn't look at the fn names, would be nice to have something like apropos
that looks at names + docs
You are, of course, free to attach implementation comments as metadata under a distinct key, which you could train your tools or documentation generator to use.
similarly methods (defined with defmethod
) don't have docstrings.
the thing is that a defmulti is just one function, you can document the function there
I think if it does different things for each value category they should be different functions
like :
(defmulti area "Calculates the area of a shape, returns a double" :type)
you can then look at all your currently supported shapes with (methods area)
You could just write your doc to explain how it works on each arity for cases where that distinction matters.
(= (into-array (map boolean-array [[true false true false true]]))
(into-array (map boolean-array [[true false true false true]])))
=> false
Why?
https://docs.oracle.com/javase/8/docs/api/java/util/Arrays.html#equals-boolean:A-boolean:A-
speak=> (java.util.Arrays/equals
(into-array [true false true false true])
(into-array [true false true false true]))
true