Clojure Q&A - Recent questions tagged docstring

`find` docstring enhancement proposal

Thu, 11 Dec 2025 12:41:48 +0000

The docstring for clojure.core/find states

Returns the map entry for key, or nil if key not present.

Formatted lower-cased with a space, it is not immediately apparent that 'map entry' is a term of art referring to a specific thing. 'map entry' might be mis-interpreted as a casual synonym for 'the entry of a map associated to a key', i.e., the value.

Proposal #1
Reword the find docstring to be more precise about what is returned.

Returns a clojure.lang.MapEntry containing key and the associated value, or nil if key not present.

Proposal #2
If you don't want to make a commitment to returning a MapEntry, reword to

Returns a sequential collection containing key and the associated value, or nil if key not present.

Docstring clojure.edn/read-string is misleading

Thu, 20 Nov 2025 15:10:38 +0000

user=> (doc clojure.edn/read-string)
-------------------------
clojure.edn/read-string
([s] [opts s])
Reads one object from the string s. Returns nil when s is nil or empty.
Reads data in the edn format (subset of Clojure data):
http://edn-format.org

opts is a map as per clojure.edn/read

Note Returns nil when s is nil or empty.. But when called with opts without explicit :eof it throws EOF error

user=> (clojure.edn/read-string {} "")
Execution error at user/eval222 (REPL:1).
EOF while reading

And without options it returns nil as expected

user=> (clojure.edn/read-string "")
nil

Support for automatic promotion to BigDecimal in +', *', etc.

Mon, 10 Nov 2025 04:15:47 +0000

Is there support for BigDecimal promotion in the +', *', etc. clojure.core functions?

When I run the following code in the REPL:

(* 2 Double/MAX_VALUE)     ;; ##Inf, Doesn't auto-promote as was expected.
(*' 2 Double/MAX_VALUE)    ;; ##Inf, Expected that it would auto promote.

Following cases also didn't work:

(*' Double/MAX_VALUE 2)        ;; ##Inf, Moving around the arguments.
(*' 2.0 Double/MAX_VALUE)      ;; ##Inf, Using a Double literal instead.
(*' Double/MAX_VALUE 2.0)      ;; ##Inf
(*' Double/MAX_VALUE 2.0M)     ;; ##Inf, Using a BigDecimal literal instead.
(*' 2.0M Double/MAX_VALUE)     ;; ##Inf

I decided to check the Clojure compiler source for promotion, and based on my limited understanding of the code I see that DoubleOps is using the implementation of addP of OpsP abstract class (which just calls the normal add function) while there is one present for LongOps which can be found here.

Is this a bug? And if yes, I would like to work on the fix and I'll check the Development page of Clojure to do the needfull.

Typo in clojure.zipper/zipper docstring

Mon, 27 Oct 2025 09:30:17 +0000

The docstring for clojure.zipper/zipper currently contains:

branch? is a fn that, given a node, returns true if can have
children, even if it currently doesn't.

which should be:

branch? is a fn that, given a node, returns true if it can have
children, even if it currently doesn't.

The docstring on empty? should perhaps not recommend using seq instead anymore

Fri, 17 Oct 2025 11:55:12 +0000

It seems the docstring on empty? is outdated, recommending to use seq to check for emptiness, even though nowodays empty? may be much faster (on counted collections):

(defn empty?
  "Returns true if coll has no items. To check the emptiness of a seq,
  please use the idiom (seq x) rather than (not (empty? x))"
  {:added "1.0"
   :static true}
  [coll]
  (if (counted? coll)
    (zero? (count coll))
    (not (seq coll))))

":added" metadata missing from some new public functions in namespace clojure.java.process

Fri, 11 Apr 2025 16:29:23 +0000

These functions in the namespace clojure.java.process are mentioned in the doc string for the namespace, and have doc strings, but do not have metadata {:added "1.12"} as do other new public docstring'ed functions in that namespace:

stdin
stdout
stderr
exit-ref

I did not find any other such functions anywhere else that are new in Clojure 1.12.0 vs. Clojure 1.11.1.

Docstring typos in clojure.core/bytes, chars, shorts

Thu, 06 Mar 2025 06:54:53 +0000

The docstring of clojure.core/bytes has a minor typo:

"Casts to bytes[]"

which should read byte[]; similarly for the docstrings of chars and shorts.

Given the new array class syntax in Clojure 1.12 perhaps these should be updated to read byte/1, float/1 etc. instead of using Java style syntax?

Incorrect docstring for parse-opts

Tue, 03 Dec 2024 16:02:27 +0000

In the docstring for clojure.tools.cli/parse-opts (seen here), it says,

:id           The key for this option in the resulting option map. This
              is normally set to the keywordized name of the long option
              without the leading dashes.

              Multiple option entries can share the same :id in order to
              transform a value in different ways, but only one of these
              option entries may contain a :default(-fn) entry.

              This option is mandatory.

The final line says "This option is mandatory." which is technically true for parse-opts' internals, but it's not true for users because (as the first paragraph says) :id is also generated by keywordizing the long option.

May I recommend changing it to be more explicit? Something like "If a long option is not provided, this option is mandatory."

Missing documentation for `:while` modifier of `for` and `doseq`

Mon, 01 Jul 2024 13:56:08 +0000

I believe the for and doseq documentation (at least docstrings) fail to explain the semantics of the :while modifier. The existence is documented, but not the behavior.

I would like to request that the doctoring be updated, especially since it behaves in what I believe is a reasonable but counter-intuitive way. I believe a reasonable person would expect that :while false would trigger the for or doseq to exit; however it does not. Rather it causes the inner-most loop containing the :while to exit, but most notably the outer loops continue to iterate.

Another discussion of this can be found here: clojurians

Clarify how to implement multi-arity methods with defprotocol

Wed, 29 May 2024 17:15:02 +0000

Hello! I have struggled to understand how to implement a multi-arity protocol method with a record, so I’d like to suggest an improvement to the defrecord docstring to make this clearer. I am thinking about this change (new is the last paragraph):

(methodname [args*] body)

The argument and return types can be hinted on the arg and
methodname symbols. If not supplied, they will be inferred, so type
hints should be reserved for disambiguation.

For multi-arity methods, add a separate (methodname ...) entry
for each one.*

clojuredoc sort is wrong with respect to comparator

Fri, 19 Apr 2024 09:51:42 +0000

The clojuredoc for sort says:
comparator MUST implement java.util.Comparator.
However, this does not seem to be the case. The function provided as 1nd argument to 2-ary sort may return explicitly true or false; it need not implement java.util.Comparator.

It would be nice if the clojuredoc were updated to reflect this important feature.

There is another document https://clojure.org/guides/comparators which explains in greater detail. But the existence of that document does not obviate (in my opinion) the short doc from being correct even if incomplete.

cljs.core/test does not work as the docstring describes

Tue, 27 Feb 2024 12:33:17 +0000

cljs.core/test does not work according to its docstring description.

The definition of cljs.core/test is

(defn test
  "test [v] finds fn at key :test in var metadata and calls it,
  presuming failure will throw exception"
  [v]
  (let [f (.-cljs$lang$test v)]
    (if f
      (do (f) :ok)
      :no-test)))

It's intended use, as far as I understand it, is as such (example copied from the documented Clojure version of the same function at ClojureDocs, https://clojuredocs.org/clojure.core/test#example-542692cac026201cdc326b8a ):

(defn my-function
  "this function adds two numbers"
  {:test #(do
            (assert (= (my-function 2 3) 5))
            (assert (= (my-function 4 4) 8)))}
  ([x y] (+ x y)))

(test #'my-function)  ;equal to (test (var my-function))
=> :ok

So, cljs.core/test enables functions to self-document their capabilities via tests made available in metadata under the :test key.

However, repeating the above in a CLJS environment yields a different result:

(defn my-function
  "this function adds two numbers"
  {:test #(do
            (assert (= (my-function 2 3) 5))
            (assert (= (my-function 4 4) 8)))}
  ([x y] (+ x y)))

(test #'my-function)
=> :no-test

The interesting thing is that, given that I evalated the above in a CLJS REPL, the metadata is available, as far as I can tell:

(meta #'my-function)
=>
{:ns cljs.user,
 :name my-function,
 :file "<cljs repl>",
 :end-column 18,
 :source "my-function",
 :column 1,
 :line 1,
 :end-line 1,
 :arglists ([x y]),
 :doc "this function adds two numbers", 
 :test #object[Function]}

This can be made even clearer by substituting the rather opaque function for a keyword:

(defn my-function
  "this function adds two numbers"
  {:test :just-a-keyword}
  ([x y] (+ x y)))

(meta #'my-function)
=>
{:ns cljs.user,
 :name my-function,
 :file "<cljs repl>",
 :end-column 18,
 :source "my-function",
 :column 1,
 :line 1,
 :end-line 1,
 :arglists ([x y]),
 :doc "this function adds two numbers", 
 :test :just-a-keyword}

I spoke to @theller and @hiredman about this on the Clojurians Slack, and they speculated that cljs.core/test has been repurposed to execute the body of deftests, since the two pieces seem to fit together. Observe:

(require '[cljs.test :as test])
(test/deftest foo (test/is (= 1 2)))
=> #'cljs.user/foo

(test foo)
FAIL in () (<NO_SOURCE_FILE>:1:28)
expected: (= 1 2)
  actual: (not (= 1 2))

:ok

The deftest body is executed and the keyword :ok is returned (regardless of the is result), as can also be gathered from reading definition of cljs.core/test.

If it is true that cljs.core/test has been repurposed in this manner, then two things are also true:

A) If it ever were the intent that cljs.core/test should enable testing :test assertions for defns, that no longer holds.
B) The docstring of cljs.core/test is somewhat misleading.

The first bit of the docstring, "test [v] finds fn at key :test in var metadata and calls it", may be technically correct, but mentions no connection with deftest, and therefore somewhat unhelpful.

The second bit of the docstring, ", presuming failure will throw exception", is certainly not correct when used for deftest - the cljs.test/is macro, which I think is fair to say that most deftests use, catches exceptions and reports instead. I think the original intent is that the execption is thrown, so :ok is not returned, but in this context, that construct fails.

The docstring seems to be a carbon copy of the Clojure version, so possibly, it warrants an update. Or maybe cljs.core/test is simply unused and redundant at this point?

Does `:exclude` need to be added to https://clojuredocs.org/clojure.core/require ?

Tue, 13 Feb 2024 19:29:06 +0000

https://clojuredocs.org/clojure.core/require makes no mention of :exclude but this seems to work as it appears:

(require '[clojure.set :refer :all :exclude [join rename]])

Dedupe doesn't mention statefullness in docstring

Mon, 22 Jan 2024 12:22:44 +0000

Unlike all other core functions which can return a stateful transducer, dedupe doesn't mention this in its docstring. E.g. distinct, drop-while etc. all say:

Returns a stateful transducer when no collection is provided.

But dedupe just says:

Returns a transducer when no collection is provided.

clojure.math/scalb docstring error

Sat, 11 Nov 2023 13:08:46 +0000

The docstring for scalb links to the documentation for nextDown, presumably just a mistake.

It links here: https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#nextDown-double-

But should link here: https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#scalb-double-int-

clojure.math/floor docstring error

Mon, 30 Oct 2023 12:55:24 +0000

In the docstring for clojure.math/floor it says:

If a is less than zero but greater than -1.0 => -0.0

but that's obviously not true:

(math/floor -0.3)
;; => -1.0

I guess it was intended to add that line to the docstring of clojure.math/ceil but added it to floor by mistake?

Typo in build.memoizer docstring

Mon, 31 Jul 2023 13:33:11 +0000

https://github.com/clojure/core.memoize/blob/master/src/main/clojure/clojure/core/memoize.clj#L267

argunments -> arguments

Document that clojure.data.int-map is sorted

Fri, 17 Mar 2023 08:58:14 +0000

Recently a question about it was asked on Slack.

This DIMAP-4 Jira ticket has made the map and the set deliberately sorted, but it was never mentioned in the docs.
Seems like it could be explicitly mentioned in the docstrings?

Docstring of with-redefs should mention usage of ^:dynamic in production

Tue, 14 Mar 2023 13:11:08 +0000

Currently, the docstring of with-redefs in CLJS reads:

cljs.core/with-redefs
([bindings & body])
Macro
  binding => var-symbol temp-value-expr

  Temporarily redefines vars while executing the body.  The
  temp-value-exprs will be evaluated and each resulting value will
  replace in parallel the root value of its var.  After the body is
  executed, the root values of all the vars will be set back to their
  old values. Useful for mocking out functions during testing.

It makes it seem as if it's perfectly fine to use it in a similar way you'd use the same macro in CLJ.
However, this comment by David Nolen says otherwise:

If you want something to be redefinable with with-redefs in production you need to mark those vars ^:dynamic.

The `keyword` and `symbol` docstrings don't mention that using `"a/b"` as its only argument is valid

Wed, 08 Feb 2023 16:53:38 +0000

The current docstrings:

clojure.core/keyword
([name] [ns name])
  Returns a Keyword with the given namespace and name.  Do not use :
  in the keyword strings, it will be added automatically.

clojure.core/symbol
([name] [ns name])
  Returns a Symbol with the given namespace and name. Arity-1 works
  on strings, keywords, and vars.

The arglists suggest that the first arity is to be used for simple idents only.
However, the underlying implementation explicitly handles the case when there's / in the value, and even the argument is named nsname:

static public Symbol intern(String nsname){
	int i = nsname.indexOf('/');
	if(i == -1 || nsname.equals("/"))
		return new Symbol(null, nsname);
	else
		return new Symbol(nsname.substring(0, i), nsname.substring(i + 1));
}

One example where some existing code relies on this behavior: transit-clj

Perhaps, the docstrings should be updated to reflect that?

Documentation for `rationalize` is misleading

Sat, 02 Apr 2022 15:15:17 +0000

It says

returns the rational value of num

but the results of (rationalize 1.6) is 8/5 instead of expected 3602879701896397/2251799813685248. What kind of rounding is performed isn't documented.