Clojure Q&A - Recent questions and answers in Docs

Answered: It's difficult to figure out options I can pass to slurp function.

Fri, 27 Feb 2026 15:11:56 +0000

This is fair. I created https://clojure.atlassian.net/browse/CLJ-2944 to track this.

Answered: Reader docs say foo.bar is a qualified symbol but qualified-symbol? is false

Mon, 12 Jan 2026 22:08:25 +0000

"Qualified" means more than one thing depending on context. Java classes are "qualified" by their package name. symbols are "qualified" by their namespace. class names are syntactically represented by a symbol which has overlapping senses - the class package is a dotted prefix that lives in the "name" part of the symbol.

qualified-symbol? is specifically referring to namespace qualification.

My guess is that Rich would say that the original sentence is correct and written as intended.

Answered: Typo in clojure.zipper/zipper docstring

Tue, 25 Nov 2025 20:32:58 +0000

Good catch! Logged as https://clojure.atlassian.net/browse/CLJ-2929

Answered: Docstring clojure.edn/read-string is misleading

Tue, 25 Nov 2025 20:14:35 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2927

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

Fri, 17 Oct 2025 14:13:15 +0000

The docstring says "To check the emptiness of a seq..." which is still the preferred idiom.

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

Fri, 11 Apr 2025 17:58:36 +0000

Thx, logged as https://clojure.atlassian.net/browse/CLJ-2906, just an oversight, they are all public API.

Answered: Can we add metaphors/analogies for functional closures in Clojure to the docs please?

Fri, 21 Mar 2025 08:41:42 +0000

Whist metaohor and analogy can be useful additions, they are subjective and not always understood. Personally I found it hard to relate to a garage containing cars with 5 people already in the car (how are more people going to get into the car, maybe it should be a bus)

Writing a more detailed article around the example above would allow more people (especially those new to Clojure) to give feedback, providing a much broader view.

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

Thu, 06 Mar 2025 16:05:51 +0000

Good catch! Logged as https://clojure.atlassian.net/browse/CLJ-2901

Answered: Found some typos in clojure.core, how to contribute a patch?

Sun, 29 Sep 2024 14:46:46 +0000

"iff" is not a misspelling, it's a common shorthand for "if and only if".

As for submitting patches - apart from signing the agreement, you also need to file a contributor support request, as per this page: https://clojure.org/dev/dev#_becoming_a_contributor

Answered: Is edn-format.org supposed to be online?

Wed, 18 Sep 2024 12:36:37 +0000

It used to redirect to the github but we think it expired and we’re still tracking down the account info.

Answered: Dedupe doesn't mention statefullness in docstring

Wed, 21 Aug 2024 15:48:54 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2879

Answered: Comparison ops "Return non-nil if..., otherwise false"

Wed, 21 Aug 2024 15:17:20 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2877

Answered: Add example to namespaced maps for :_/foo functionality

Wed, 03 Jul 2024 13:24:31 +0000

The reference pages by design do not contain exhaustive sets of feature examples. The goal of the example here is to demonstrate the most common usage of namespace map syntax. So, I don't think we need to add :_/foo to the example here (it would not make sense).

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

Mon, 01 Jul 2024 14:00:44 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2869

Answered: Documentation on alternative radix/0-prefixed numbers

Tue, 30 Apr 2024 17:07:47 +0000

There are some docs on the reader page under https://clojure.org/reference/reader#_literals

Those examples all look right to me.

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

Wed, 14 Feb 2024 18:04:54 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2837

Answered: `hash-map` without arguments returns an array map, despite the docstring

Sun, 11 Feb 2024 21:37:48 +0000

The point of confusion here is that "persistent hash map" is the abstraction here, but there are two concrete implementations: hash-map (PersistentHashMap) and array-map (PersistentArrayMap), and the latter changes type to the former based on map size.

hash-map is a constructor for the abstraction of persistent hash maps (generic), and makes no promises about the returned concrete type. However array-map IS (explicitly) a constructor for array-maps. There is no constructor function explicitly for PersistentHashMap.

Typo in the release notes for 1.12.0-alpha6

Fri, 09 Feb 2024 00:51:06 +0000

This under Array Class Symbols

Clojure supporst class symbols

should be

Clojure supports class symbols

Answered: The new add-lib etc fns do not make it clear they shell out to the CLI

Mon, 11 Dec 2023 21:29:54 +0000

Jira ticket clj-2819 has been created to track this issue.

Answered: clojure.math/scalb docstring error

Mon, 13 Nov 2023 17:20:45 +0000

Jira and patch logged at: https://clojure.atlassian.net/browse/CLJ-2811

Answered: clojure.math/floor docstring error

Mon, 30 Oct 2023 14:00:17 +0000

Yep, logged as https://clojure.atlassian.net/browse/CLJ-2809

Answered: update-vals documentation string has a typo

Fri, 15 Sep 2023 22:25:19 +0000

I think the docstring is correct as written. f is applied to the values of m (as it says). The map returned is a map from the original keys to the new values.

Links to EPL license are now broken

Wed, 23 Aug 2023 17:16:20 +0000

Links such as https://github.com/clojure/clojure/blob/2a058814e5fa3e8fb630ae507c3fa7dc865138c6/test/clojure/test_clojure/protocols.clj#L3C33-L3C79 direct one to a 404 page.

Answered: Could `clojure.zip/next` docstring be misleading to some?

Sat, 08 Apr 2023 13:06:35 +0000

"returns a distinguished loc" is clear: the zipper's end marker is not one of the nodes.

Webster's Second Unabridged (1956) defines "distinguished" as "distinct; differentiated". As for a computer-science definition of "distinguished value", I did not find one online, but OpenAI Chat got it right, so it must be out there somewhere: 'the term "distinguished value" typically refers to a specific value within a data structure or system that has a special meaning or purpose. This value is often used as a marker or sentinel to indicate the beginning or end of a certain section of data or to signal a certain condition or state. For example, in a linked list data structure, the value "NULL" is often used as a distinguished value to indicate the end of the list..'

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

Wed, 01 Mar 2023 16:20:49 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2751

Answered: Add example of clojure -Sdeps to Deps and CLI guide or reference

Tue, 04 Oct 2022 21:15:26 +0000

The clojure site repo accepts PRs in case you feel like suggesting a concrete edit https://github.com/clojure/clojure-site/pulls

Answered: Document that distinct preserves ordering

Wed, 15 Jun 2022 18:14:26 +0000

I don't think we want to say more than it says. If you pass a sequence or sequential collection, then it returns a "sequence of the elements" - it seems natural to expect the sequential elements to be returned in the same order.

On the flip side, if the coll passed to distinct is unordered and not sequential (ie a map or set), this function cannot make promises about the order of the results.

It is also intentionally ambiguous which equal element you will get in the result (but again, the first in a sequential coll seems like the obvious answer).

Answered: Documentation for `rationalize` is misleading

Wed, 06 Apr 2022 16:10:08 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2703

Answered: doall docstring

Mon, 27 Dec 2021 23:34:08 +0000

I'm either not understanding the doc string, or it needs to be substantially changed:

When lazy sequences are produced via functions that have side
effects, any effects other than those needed to produce the first
element in the seq do not occur until the seq is consumed. doall can
be used to force any effects. Walks through the successive nexts of
the seq, retains the head and returns it, thus causing the entire
seq to reside in memory at one time.

(ins)user=> (defn printed-range [n] (map print (range n)))
#'user/printed-range
(ins)user=> (let [x (printed-range 10)] nil)
nil
(ins)user=> (let [x (printed-range 10)] (first x))
0123456789nil

the doc seems to say that the first element will b realized, but only elements that are accessed are guaranteed to be realized

Answered: Invoke Clojure with an argument

Mon, 27 Dec 2021 01:07:37 +0000

clojure -J--illegal-access=debug

clojure -J--illegal-access=debug -M -e '*clojure-version*'

The -J option is used to pass arguments to the JVM when the Clojure CLI runs.

Answered: Typo in https://clojure.org/guides/tools_build

Sat, 04 Dec 2021 22:21:29 +0000

Given that the main ns is specific to the project, I wonder if it would be better to have:

(def main-ns 'my.lib.main)

at the top (after lib, say) and then use that var in the call to uber?

(b/uber {:class-dir class-dir
         :uber-file uber-file
         :basis     basis
         :main      main-ns})

Then it might be worth showing an alternative call to compile-clj that just compiles that main ns instead of implicitly compiling "all" -- and show that :src-dirs can be [] when :ns-compile [main-ns] is provided?

Answered: requesting change to doc string in (doc take-while)

Tue, 09 Nov 2021 21:25:13 +0000

Hi, thanks for the suggestion, but I don't think we will change this.

"while (pred item) returns logical true" is sufficient - "while" means "during the time when the condition holds" (and not when it doesn't). "I sing while I'm in the shower" does not need to also say "and stop singing when I get out of the shower".

Clojure core docstrings are intentionally very economical in their language. They are of course imperfect and nearly every release of Clojure has docstring updates, so we're open to changing them where that makes sense, but I don't think that's the case here.

Many beginners need additional information and we have great ancillary resources like https://clojuredocs.org/clojure.core/take-while where Clojure users can provide examples, additional commentary, links, etc to supplement the core docstring. The Clojure cheatsheet (https://clojure.org/api/cheatsheet) provides links into ClojureDocs as well.

Answered: clojure.java.api documentation mistaken example

Wed, 27 Oct 2021 19:12:36 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2666

Answered: Docstring for `=` could be made less ambiguous w.r.t. numbers

Sun, 17 Oct 2021 13:23:54 +0000

I do not know the Clojure maintainer's views on this idea, but an approach that would make the details easier to find for many people, without significantly increasing the length of the compiled-into-the-Clojure-image doc string, would be to add a sentence like "For additional details, see https://clojure.org/guides/equality" in the doc string.

Answered: What do the metalanguage-style symbols on clojuredocs.org mean?

Sat, 19 Jun 2021 20:06:41 +0000

You may find this useful:

https://clojure.org/guides/weird_characters

Answered: Add warning about not using the ret-val of `assoc!` to the doc string

Fri, 23 Apr 2021 21:55:59 +0000

This is logged already as https://clojure.atlassian.net/browse/CLJ-1385 (I think it was waiting on me for a better message iirc).

Answered: Which argument is which, for bit-shift-left and bit-shift-right?

Fri, 12 Feb 2021 16:43:05 +0000

Filed jira: https://clojure.atlassian.net/browse/CLJ-2608

Answered: Typo in Getting Started: /etc/man_dev.conf ➡ /etc/man_db.conf

Mon, 01 Feb 2021 04:15:31 +0000

Hi, the best place to file web site issues/PRs is here: https://github.com/clojure/clojure-site/issues

Thanks!

Answered: Is "port" inside core.asyn documentation same as a "chan"?

Wed, 30 Dec 2020 15:48:01 +0000

A port is the read or write end of a chan. So you can think of most channel instances as having both a read and write port on both ends. In some cases the api may actually give you only a read or write port impl though and not a full chan.

The read and write port protocols are defined at
https://github.com/clojure/core.async/blob/master/src/main/clojure/clojure/core/async/impl/protocols.clj#L15.

Answered: Document how extend-type can be used to provide default protocol implementation

Tue, 22 Dec 2020 15:29:08 +0000

Logged improvement request as https://clojure.atlassian.net/browse/CLJ-2595

Answered: CLI/deps reference use of :aliases is confusing in a couple of places

Tue, 08 Dec 2020 15:58:56 +0000

Seems reasonable. That's actually pulled from clj -h though so need to consider how to sync those up. clj man page uses slightly different syntax like -X[:alias...].

Answered: Is it legal to apply keys / vals to a sequence of map entries?

Sun, 22 Nov 2020 18:19:45 +0000

Yes, this is legal and you can rely on it.

I also logged a ticket to either update the docstring or even make this more explicit in the types:

https://clojure.atlassian.net/browse/CLJ-2592

Answered: doc string for reify is missing a statement of what it does

Mon, 16 Nov 2020 15:34:28 +0000

Logged as https://clojure.atlassian.net/browse/CLJ-2591

Clojure Generation PDF blockchain

Mon, 27 Jul 2020 23:41:31 +0000

Hi guys, I'm going to start developing a project and I want you to recommend some technologies that I can use and be useful for my project.

Currently I have a system that generates PDF documents, but these documents do not have any type of security, what I want is: Generate PDF documents using blockchain and create a transactional query application for the generated documents

Can someone make a recommendation to start my project?

Thank you.!

What is the big O for clojure operations?

Wed, 15 Jul 2020 18:49:21 +0000

Hi, I'm new to clojure.

I have seen that there are some big O on the data structures part. But, is there a place on documentation showing all the big O of the operations in clojure?

Thanks!

How to see related functions in cider doc?

Tue, 14 Apr 2020 04:19:35 +0000

When using Cider, C-c C-d C-d shows the doc for a given functions. There should be a "See also" section at the bottom of the doc, listing related functions(e.g. "doseq" refers to "for"). However it's gone somehow. Did I accidentally turned it off or something? How do I get it back?

And by the way, where did that "related functions" information come from? It's not written in the doc string...

Should (doc get) 'format/example' refer to the 'associative' abstraction rather than a 'map'?

Fri, 20 Dec 2019 15:20:12 +0000

(doc get) returns
"-------------------------
clojure.core/get
([map key] [map key not-found])
Returns the value mapped to key, not-found or nil if key not present."

As 'get' works for a vector, as well as a map, I think the function addresses the associative abstraction, so this format would be less misleading:

([associative key] [associative key not-found])

Thanks to the experts at ClojureVerse who confirmed that my confusion at the example was justified and suggested I report it here.

Make clojure.core/get docstring more like clojure.core/get-in?

Wed, 27 Nov 2019 14:41:18 +0000

The docstring for get is:

Returns the value mapped to key, not-found or nil if key not present.

Multiple people at my work have found that sentence confusingly terse and hard to parse.

The docstring for get-in is:

Returns the value in a nested associative structure, where ks is a sequence of keys. Returns nil if the key is not present, or the not-found value if supplied.

Could the docstring for get be changed to:

Returns the value mapped to key. Returns nil if the key is not present, or the not-found value if supplied.

Logged and patch attached at: https://clojure.atlassian.net/browse/CLJ-2544

Migration from Closure to Python 3

Wed, 13 Nov 2019 04:15:39 +0000

Hello,

I would like to see if it is possible to migrate Closure code to Python.
Is-it possible? Do we have some scripts available to help for this?

I'm Python coder but don't have any expertise within Closure.

Can you help me?
Thanks in advance for your answers

Best regards,
Raoul

Doc strings for spit and clojure.java.io/writer mention but do not explain opts

Mon, 01 Apr 2019 19:42:55 +0000

I was trying to point my users at the reference documentation for spit to help them understand how they could customize output, and found that the options like :append true are not documented. Even if they are resourceful enough to figure out how to get to the docstring for clojure.java.io/writer itself, the options are not documented there either. I would basically need to teach them how to open a repl to explore the source code, or find it on GitHub, in order to figure this stuff out. Since they are generally not software developers, but musicians or their lighting/visuals staff trying to use a tiny bit of Clojure code to glue together shows, it would be nice if this information was easier to surface.

Some of this information can be found by scrolling down into examples on clojuredocs.org, but it would seem nice to have a definitive list of the options supported in the doc strings themselves.

Patch: clj-2500.patch