Fork me on GitHub
#beginners
<
2023-09-07
>
Jim Newton11:09:39

it is unfortunate that a multi-arity defn cannot take separate docstrings for each arity 😞

jpmonettas12:09:15

I guess if a function does different things depending on the arity, then they should be different functions, with different names

Jim Newton12:09:21

who is the audience of the docstring?

teodorlu12:09:41

different docs for each arity would probably require a different way to store the docstring:

(defn myfn
  "Myfun docstring"
  [])

(:doc (meta #'myfn))
;; => "Myfun docstring"

jpmonettas12:09:22

> who is the audience of the docstring? the function users

Jim Newton12:09:21

so documentation for implementors should just co in comments?

jpmonettas12:09:34

for the developer of the function, which are going to be looking at the code, you normally use clojure comments with ; yeah

jpmonettas12:09:04

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

jpmonettas12:09:12

it would be nice if apropos also searched in doc strings

dpsutton12:09:08

You can search doc strings

dpsutton12:09:28

find-doc I think

jpmonettas12:09:37

oh but find-doc doesn't look at the fn names, would be nice to have something like apropos that looks at names + docs

phill13:09:14

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.

2
Jim Newton14:09:19

similarly methods (defined with defmethod) don't have docstrings.

dpsutton14:09:47

how would you get the docstrings of the different ones?

dpsutton14:09:53

(doc some-method)

jpmonettas14:09:44

the thing is that a defmulti is just one function, you can document the function there

jpmonettas14:09:33

I think if it does different things for each value category they should be different functions

jpmonettas14:09:26

like :

(defmulti area "Calculates the area of a shape, returns a double" :type)

jpmonettas14:09:32

you can then look at all your currently supported shapes with (methods area)

Ingy döt Net14:09:32

You could just write your doc to explain how it works on each arity for cases where that distinction matters.

Joel21:09:59

(= (into-array (map boolean-array [[true false true false true]])) (into-array (map boolean-array [[true false true false true]]))) => false Why?

dpsutton21:09:39

arrays are comparable by reference, not by value

dpsutton21:09:56

same reason as the following:

(= (Object.) (Object.))
false

Joel21:09:11

is there an operator to compare them?

Joel21:09:41

surprised i hadn’t run into this before, but i tend to stay in clojure land. Thanks.

dpsutton21:09:27

speak=> (java.util.Arrays/equals
          (into-array [true false true false true])
          (into-array [true false true false true]))
true

dpsutton21:09:43

doesn’t seem to like your nested arrays as presumably those are not “equal” to each other

Joel21:09:33

but deepEquals works!

💪 2