Clojure Q&A - Recent activity in Docs

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

Sat, 28 Feb 2026 06:27:25 +0000

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

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

Mon, 12 Jan 2026 22:24:55 +0000

Syntax error (ClassNotFoundException) compiling at (REPL:2:1).
page.html

I was not expecting that :)

Retagged: Typo in clojure.zipper/zipper docstring

Tue, 25 Nov 2025 20:33:12 +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.

Answer selected: Docstring clojure.edn/read-string is misleading

Tue, 25 Nov 2025 20:24:34 +0000

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

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

Fri, 17 Oct 2025 14:17:28 +0000

Ah, thank you, I haven't read the docstring carefully enough. I read it as "a sequential collection" while it literally means "an implementation of `ISeq`"

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

Mon, 02 Jun 2025 15:04:50 +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.

Answer selected: Add example to namespaced maps for :_/foo functionality

Thu, 15 May 2025 18:34:06 +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: 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

Closed: clojure.core/assert docstring is incorrect

Sun, 17 Nov 2024 16:20:09 +0000

The {{assert}} macro has two arities, documented as {{(assert x)}} and {{(assert x message)}}

The docstring is:
{quote}
Evaluates expr and throws an exception if it does not evaluate to logical true.
{quote}

This is quite misleading since {{assert}} actually throws an {{Error}}. It is tempting to use {{assert}} assuming that a failure will lead to a stacktrace in logs, like any other {{Exception}}, but the reality is that the JVM will terminate.

The behaviour is correct, {{assert}} should cause a program to exit if the asserted condition is true but I regularly come across incorrect uses.

I'll work up a patch if people agree this is an issue.

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

Sun, 29 Sep 2024 14:54:03 +0000

Thanks, didn't know about this `iff` thing.

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.

Retagged: Dedupe doesn't mention statefullness in docstring

Wed, 21 Aug 2024 15:49:02 +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.

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

Wed, 21 Aug 2024 15:43:42 +0000

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

Commented: partition-all docstring should mention it returns vectors in transducer case

Tue, 06 Aug 2024 20:54:19 +0000

yes, the docstring has overstated what you should expect all these years. The transducer is new so making it different breaks no existing code.

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

Mon, 29 Jul 2024 19:04:48 +0000

https://clojure.github.io/clojure/branch-master/clojure.repl-api.html#clojure.repl.deps

Neither the ns docstring nor the individual function docstrings explain that they shell out to the CLI and that you need a recent version of the CLI installed.

Having an old CLI might produce this error:

Execution error (ExceptionInfo) at clojure.tools.deps.interop/invoke-tool (interop.clj:49).

Which might be enough of a clue to lead people to:

https://clojure.github.io/clojure/branch-master/clojure.tools.deps.interop-api.html

A more informative error message might help users debug this but expanding those docstrings to clarify that the functions invoke the CLI as a subprocess would also help.

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

Mon, 01 Jul 2024 14:00:56 +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

Closed: Docstrings for `conj!` and `assoc!` should suggest using the return value; effect not always in-place

Sat, 15 Jun 2024 15:12:53 +0000

The docstrings of both assoc! and conj! say "Returns coll.", possibly suggesting the transient edit happens (always) in-place, coll being the first argument. However, this is not the case and the returned collection should always be the one that's used.

Approach: Replace "Returns coll." with "Returns an updated collection." in conj(image: , assoc), pop! docstrings.

Patch: CLJ-1385-reword-docstrings-on-transient-update-funct-2.patch

Screened by: Alex Miller

Commented: Documentation on alternative radix/0-prefixed numbers

Tue, 30 Apr 2024 17:55:46 +0000

Alright, thanks.

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

Wed, 14 Feb 2024 18:05:22 +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]])

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

Mon, 12 Feb 2024 08:17:48 +0000

With `(binding [*print-dup* true] (prn {}))`.

Closed: Typo in the release notes for 1.12.0-alpha6

Fri, 09 Feb 2024 01:58:53 +0000

This under Array Class Symbols

Clojure supporst class symbols

should be

Clojure supports class symbols

Answer selected: clojure.math/scalb docstring error

Mon, 13 Nov 2023 23:24:13 +0000

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

Answer selected: clojure.math/floor docstring error

Mon, 30 Oct 2023 14:12:09 +0000

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

Answer selected: update-vals documentation string has a typo

Sat, 16 Sep 2023 02:50:34 +0000

The doc string is correct. In a map, the keys are mapped to their values. update-vals returns a new map where the keys are mapped to the new values. "Mapped" in those cases means "linked to" and not "being passed to some function".

Commented: Links to EPL license are now broken

Thu, 24 Aug 2023 02:10:42 +0000

well, I don't think we're going to change the link in every source file

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

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

Wed, 01 Mar 2023 17:13:20 +0000

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

Commented: Invoke Clojure with an argument

Thu, 26 Jan 2023 04:59:32 +0000

No idea about CIDER, sorry.

As fir the FAQ: https://github.com/clojure/clojure-site/pull/636

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

Tue, 18 Oct 2022 15:46:06 +0000

Oh good call, I'll see if I can write up something useful.

Commented: Document that distinct preserves ordering

Thu, 16 Jun 2022 09:34:51 +0000

The strongest hint is that API doc says, "Returns a lazy sequence...".

Answer selected: Documentation for `rationalize` is misleading

Fri, 08 Apr 2022 09:36:26 +0000

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

Commented: doall docstring

Tue, 28 Dec 2021 11:23:29 +0000

An adequate correction would simply change "do not" to "might not".

Most docstrings are more narrowly scoped. doall is relatively extravagant with its fable. A more thorough fix would be to remove the (over-simplified) general info, on the theory that this isn't the place.

P.S. The exact same observation applies to dorun.

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?

Closed: Typo in docstring of test-vars

Tue, 23 Nov 2021 21:05:01 +0000

Patch fixes docstring: "runs test-vars" should be "runs test-var".

Screened by: Alex Miller

Closed: compiler-options docstring is missing :direct-linking

Tue, 23 Nov 2021 20:53:59 +0000

Docstring was never updated to add :direct-linking.

Proposed: Add line:

clojure.core/*compiler-options* A map of keys to options. Note, when binding dynamically make sure to merge with previous value. Supported options: :elide-meta - a collection of metadata keys to elide during compilation. :disable-locals-clearing - set to true to disable clearing, useful for using a debugger :direct-linking - set to true to use direct static invocation of functions, rather than vars Alpha, subject to change.

Patch: clj-2326.patch

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

Tue, 23 Nov 2021 20:53:09 +0000

While the doc string for the function reify is quite detailed, it never seems to say what it does. The addition of a single sentence near the beginning of the doc string, perhaps one similar to the following, would help:

"reify defines an anonymous type, and creates and returns an instance of that type."

Note: The reference documentation for reify on clojure.org is better in this regard https://clojure.org/reference/datatypes#_reify and I copied then edited one of the sentences there to create the one proposed above.

Closed: Improve docstring for reify

Tue, 23 Nov 2021 20:52:14 +0000

I think the docs for reify says a lot about how but misses the point for what "reify" does.

user=> (doc reify)

clojure.core/reify
([& opts+specs])
Macro
reify is a macro with the following structure:

(reify options specs)
...
`

Proposed: Add a definition of what reify does:

user=> (doc reify)

clojure.core/reify
([& opts+specs])
Macro
reify creates an anonymous instance implementing a protocol or interface.
reify is a macro with the following structure:

(reify options specs)
...
`

Patch: clj-2488-2.patch

Screened by: Alex Miller

Closed: Document behavior of clojure.core/get on strings and Java arrays

Tue, 23 Nov 2021 20:50:53 +0000

get's implementation checks in order for

ILookup
nil
Map
IPersistentSet
String or Java array

The docstring for get currently reads

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

That this works on maps and associative data can reasonably be inferred if one knows Clojure's data model. That it works on sets, Strings, and arrays is less obvious, and would be helpful to mention.

Patch: clj-2249-3.patch

Closed: Doc that clojure.string/split strips trailing delimiters

Tue, 23 Nov 2021 20:50:19 +0000

clojure.string/split and clojure.string/split-lines inherit the bizarre default behavior of java.lang.String#split(String,int) in stripping trailing consecutive delimiters:

(clojure.string/split "banana" #"an")
⇒ ["b" "" "a"]
(clojure.string/split "banana" #"na")
⇒ ["ba"]
(clojure.string/split "nanabanana" #"na")
⇒ ["" "" "ba"]

In the case of split-lines, processing a file line by line and rejoining results in truncation of trailing newlines in the file. In both cases, the behavior is surprising and cannot be inferred from the docstrings. A workaround for split is to pass a limit of -1.

*Proposed:* As current users may be relying on the current behavior, the attached merely updates the docstring to warn of this behavior and suggest use of -1 as a limit to workaround.

*Patch:* clj-1360-2.patch

Closed: clojure.java.api documentation mistaken example

Tue, 23 Nov 2021 20:49:33 +0000

In the current text of clojure.java.api, there is an text explaining that IFn can be passed to HOF.

Then an example is presented as "passing plus to read" but I think the example is actually passing inc to map.

This is the current text:

IFns can be passed to higher order functions, e.g. the example below passes plus to read:

IFn map = Clojure.var("clojure.core", "map");
IFn inc = Clojure.var("clojure.core", "inc");
map.invoke(inc, Clojure.read("[1 2 3]"));

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

Wed, 10 Nov 2021 21:38:21 +0000

Thanks for taking the time to reply.

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.

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

Wed, 21 Jul 2021 15:55:36 +0000

Thank you very much for your reply, will do it then.

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

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

Sat, 24 Apr 2021 05:58:23 +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).

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

Mon, 15 Feb 2021 01:59:37 +0000

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

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

Mon, 01 Feb 2021 06:55:46 +0000

OK, thanks. I opened an issue: https://github.com/clojure/clojure-site/issues/502

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

Wed, 30 Dec 2020 23:58:40 +0000

Yes, that’s correct

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

Thu, 10 Dec 2020 22:14:28 +0000

Thanks! First glance over the updated help and docs all looks good!

Clojure Q&A - Recent activity in Docs

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

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

Retagged: Typo in clojure.zipper/zipper docstring

Answer selected: Docstring clojure.edn/read-string is misleading

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

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

Answer selected: Add example to namespaced maps for :_/foo functionality

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

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

Closed: clojure.core/assert docstring is incorrect

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

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

Retagged: Dedupe doesn't mention statefullness in docstring

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

Commented: partition-all docstring should mention it returns vectors in transducer case

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

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

Closed: Docstrings for `conj!` and `assoc!` should suggest using the return value; effect not always in-place

Commented: Documentation on alternative radix/0-prefixed numbers

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

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

Closed: Typo in the release notes for 1.12.0-alpha6

Answer selected: clojure.math/scalb docstring error

Answer selected: clojure.math/floor docstring error

Answer selected: update-vals documentation string has a typo

Commented: Links to EPL license are now broken

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

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

Commented: Invoke Clojure with an argument

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

Commented: Document that distinct preserves ordering

Answer selected: Documentation for `rationalize` is misleading

Commented: doall docstring

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

Closed: Typo in docstring of test-vars

Closed: *compiler-options* docstring is missing :direct-linking

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

Closed: Improve docstring for reify

user=> (doc reify)

user=> (doc reify)

Closed: Document behavior of clojure.core/get on strings and Java arrays

Closed: Doc that clojure.string/split strips trailing delimiters

Closed: clojure.java.api documentation mistaken example

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

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

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

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

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

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

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

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

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

Closed: compiler-options docstring is missing :direct-linking