I'd go one step further and add a replacement macro for defn so that you don't have to split the function and the docs.

But also, if you only have "args -> return" in that comment, you can already use function specs for that.

Also somewhat relevant: https://github.com/danielcompton/defn-spec

i almost feel like changing a core function like defn makes the code base feel really scary. I know that sounds silly, but i personal always get anxiety when i open a new codebase and it's like "good bye clojure hello xyz". Maybe i need to find a way to make the macro more approachable though?

but yea, combining them as that advantage for sure.

both can probably exists. defn-spec is defiantly looks inspirational, thanks for sharing it 🙂

how about using the test metadata? that would also verify that the example you give actually works

Interesting. Whenever I see "xyz", I just immediately browse its source code and read its docstring, and that solves most of the inconveniences caused by some new thing I've never seen before. So if I saw some defn+, it wouldn't be an issue at all for me. And you can make your IDE (at least Cursive but probably any other) work with it as well by resolving it as defn and putting those comments within the metadata of the function.

> the test metadata What do you mean?

I haven't personally used it, but I meant stuff like https://clojuredocs.org/clojure.core/test & https://clojuredocs.org/clojure.test/with-test. I assume those can be integrated with clojure.test

I recall reading some blog post about that, but can't find it anymore. Theres some discussion about that here: https://clojureverse.org/t/inline-tests-do-you-do-it/4083

Ah, yeah. At some point, I found clojure.core/test to be too verbose and came up with this: https://clojurians.slack.com/archives/C03RZGPG3/p1650322293208149?thread_ts=1650317272.864349&cid=C03RZGPG3 But none of that is compatible with the requirement in the OP - to be able to use doc to see the example code. Which, of course, might not be a strict requirement - up to Drew.

I mentioned doc, but my actual goal would be more abstract. Just a way to reach, first and foremost, myself in the future with some easy to reach examples that i would have created without any effort. Secondly, reaching as big of an audiance as possible, i assume most editors pick up the doc string information so that's a safe bet. Though now that i'm saying this outload, i realize that i don't know how an editor could use my hypothetical "comment fn macro" as a doc string for a function.

Yeah, then using :test would probably make more sense because at least it's something built-in - some editors might know about it and display it to their users.

i like that option.

> i almost feel like changing a core function like defn makes the code base feel really scary. Me too. 👍

Condensing the discussion above, it sounds like comment-fn is a macro that will add it's body to both the :doc and :test metadata of the fn. I'd definitely use that! :star-struck:

Interesting question. I don’t know the answer, but it spurred me to think whether it would make sense for tooling to support for a “Show Examples”-type command. When your caret is on a symbol naming a function or a macro and you run the command, if there’s a file called examples/{your-fn-name}.repl in the classpath, the tooling would open it (perhaps side-by-side with the original view), with (in-ns 'your.namespace) tacked at the top of the file to make it easy to evaluate the examples in the context of your namespace. That way the examples would be at hand and easy to work with. :thinking_face:

I like it. ✔️

I'm going to try do work on this for an hour in #C04547H53TK right now. i'm half asleep and don't know how to write macros. join at your own risk.

In just a short time, and half asleep with a crashing editor, i made some good progress with help from @U06S1EJPL. It was a lot of fun, i never had a strong urge to try my hand at a macro before. https://github.com/drewverlee/comment-injected-into-function

I’d expect it to throw some kind of exception, the same as nth. nth documents that if will throw unless it gets a not-found argument. What else could one expect when asked to get a random element from an empty collection? nil?

rand-nth does not hide that it uses nth, so I’d not consider that an implementation detail: > Return a random element of the (sequential) collection. Will have > the same performance characteristics as nth for the given > collection.

Getting the first of an empty collection returns nil, so i wouldn't find this behavior strange

I don't think that getting a random element from a collection to be so different from getting the first (or last) element from a collection, wrt to expected behavior

You could argue the same for nth though.

user=> (get [] 0)
nil
user=> (nth [] 0)
java.lang.IndexOutOfBoundsException [at <repl>:4:1]

Docstring for nth: > Returns the value at the index. get returns nil if index out of > bounds, nth throws an exception unless not-found is supplied. nth > also works for strings, Java arrays, regex Matchers and Lists, and, > in O(n) time, for sequences.

It seems wrong to me that (rand-int 0) is defined. I can understand what is a N-sided dice if N is positive, but what is a 0-sided dice ?

>

Returns a random integer between 0 (inclusive) and n (exclusive).

Yeah, I'd agree this makes no sense on empty vectors, and comparing it to first is comparing two different abstractions. first is from the sequence abstraction which has defined behavior over empty sequences. nth and friends are all specifically defined to return index out of bounds if you index somewhere wrong, so I expect rand-nth with an empty collection to throw. What I don't expect is for that exception to be based on indexing, I expected rand-int to throw when passed 0, but either way rand-nth is displaying correct behavior.

It might not be the same thing, but your description has some overlap with https://vlojure.io/

Also probably not the same thing, but there are some interesting projects and results discussed at https://clojureverse.org/t/wip-a-visual-blocks-engine-for-clojure-need-your-input/790

This in particular looks similar, albeit it's in CL and not Clojure: https://github.com/honix/Lire

@U2FRKM4TW, that's a really interesting post... from 5 years ago! Very cool! 🤯

@U7RJTCH6J yes yes yes!! 😄

thank you very much!