Fork me on GitHub
#clojure
<
2021-11-15
>
jumar08:11:27

Where do people put package-level documentation? Let's say I have an app with structure like:

myapp/src/
- users
- admin
- plans
  - a.clj
  - b.clj
  - c.clj
...
Now I want to write some docs that apply to most of the things in the plans directory. E.g. In java, there's package-info.java that can serve this purpose.

Alex Miller (Clojure team)12:11:43

Namespace metadata is probably the closest

jumar14:11:38

@U064X3EF3 what do you mean by namespace metadata? I would put higher-level docs in ns docstring but here I'm asking about docs that apply to multiple namespaces.

Alex Miller (Clojure team)14:11:35

I meant ns docstring. there is no other place

Alex Miller (Clojure team)14:11:52

there's no equivalent of package-info.java

winsome15:11:23

Is it docs for developers? Because I've seen people just put a README in a directory before. I've also worked on a project that had an "adr" (Architecture Decision Record" directory that would have a markdown file that discusses a "package" of namespaces.

jumar18:11:45

Yeah, readme.md is one alternative I considered

Dr. Moltu10:11:50

Hi, can anyone confirm that containsAll() implementation in PersistentQueue is not correct? thx

public boolean containsAll(Collection c) {
    for (Object o : c) {
        if (contains(o))
            return true;
    }
    return false;
}

opqdonut10:11:19

looks more like containsAny, yeah

jumar11:11:53

I'm curious how did you find that 🙂

Dr. Moltu11:11:46

So I'm interested in persistent batched queues, while reading the Clojure implementation, I found it :D

Colin P. Hill13:11:36

Anyone have any examples of the queue usage patterns Rich is talking about https://youtu.be/ROor6_NGIWU?t=1933? He talks about how the queues in java.util.concurrent are underused, and suggests that this might be because he didn't wrap them (as they can be used in their native Java form). Checking git history, looks like this talk was 9 years after his first cut of clojure.lang.PersistentQueue, so it seems like he's talking about something other than this.

Colin P. Hill13:11:19

I can understand the principles of what he's saying and it makes good sense, but I'm having a hard time imagining how the plumbing fits together

Alex Miller (Clojure team)13:11:04

core.async incorporates a lot of these ideas

Alex Miller (Clojure team)13:11:22

PQ (being persistent) is not really relevant, since it's persistent (I rarely use it in anything other than a single-threaded context)

Alex Miller (Clojure team)13:11:07

the Deque / Transfer stuff in juc is probably the most interesting for the things he's talking about here, and core.async channels have a lot of the Transfer queue semantics

Colin P. Hill13:11:38

Oh, I was scouring the source of core.async for java.util.concurrent and then realized I might have misunderstood you – do you mean that core.async is essentially the Clojure equivalent he was saying hadn't yet (at this point) been written?

Alex Miller (Clojure team)13:11:22

I think the kernel of the ideas were probably there at that point

Colin P. Hill13:11:45

Got it. I'll look into guides on use of core.async then. Thank you!

Alex Miller (Clojure team)13:11:54

and eventually became core.async

Alex Miller (Clojure team)13:11:07

Clojure Applied has a couple chapters on core.async

wombawomba14:11:49

I want to create something like a type alias for ExceptionInfo — i.e. a class that extends it but just slaps a new name on it and otherwise delegates everything to the original class. What's the easiest way to do this?

Alex Miller (Clojure team)14:11:22

the whole point of ExceptionInfo is it carries a data map that you can add additional information to

wombawomba14:11:43

I'm interfacing with code written by others and I want to be able to throw something that acts exactly like an ExceptionInfo but has a different class name.

wombawomba14:11:06

(so that calling code can catch this exception type and ExceptionInfo separately)

wombawomba14:11:45

(I want it to work like ExceptionInfo because I like the way ExceptionInfo works)

Alex Miller (Clojure team)14:11:16

it's probably easier to re-implement IExceptionInfo and make a new type, than to proxy or subclass ExceptionInfo itself

Alex Miller (Clojure team)14:11:26

there's almost nothing in ExceptionInfo

Alex Miller (Clojure team)14:11:55

it's just an exception carrying a map

Noah Bogart14:11:06

i’ve been reading about protocols and how most of the clojure.core functions in the java implementation use interfaces whereas the javascript implementation use protocols. (see this discussion https://stackoverflow.com/questions/27728133/extending-clojure-core-protocols about nth for an example). i realize the reason clojure didn’t switch over at the release of 1.2 was backwards compatibility and we’re now well past when any such breaking changes would be considered. but has anyone ever attempted to reimplement the clojure.core functions with protocols as “clojure 2.0” library?

Alex Miller (Clojure team)15:11:15

not to my knowledge. it would dramatically affect the java/clojure split and how collections were implemented I think. certainly clojurescript is the best reimagining by the person with the most context :)

Noah Bogart15:11:46

yeah, it makes sense from a pragmatic standpoint, as interfacing with java is a big reason to use clojure, but it’s a pain point when working strictly within clojure that the existing architecture isn’t enough to do this stuff. i’ve never actually looked at clojurescript’s core library or how it’s implemented. maybe i’ll take a wack at it myself to see how things break!

Alex Miller (Clojure team)17:11:33

if you do, I have been told that looking at the very early commits of clojurescript (not where it is now) is probably the best entry point

👍 1
wombawomba14:11:43

Fair enough. Is gen-class the way to go here, or is there some other, simpler way of doing it?

Alex Miller (Clojure team)14:11:19

I guess you have to extend something to make it an exception, so either gen-class or proxy

wombawomba14:11:43

Alright, thanks 🙂

jdkealy16:11:41

In a ring app, how do i access the body of a text/plain POST ? My repl just hangs when i attempt to slurp the body. The body shows #object[org.eclipse.jetty.server.HttpInputOverHTTP 0x4f4b65da "HttpInputOverHTTP@4f4b65da[c=0,q=0,[0]=null params shows {}

Felipe02:11:19

are you def’ing the response and trying to slurp after the request is handled?

restenb18:11:14

the syntax in alt! has me confused. i'm trying to exit a go-loopthrough a signalling "exit channel". would this be the right approach?

restenb18:11:54

(alt! (blocking-operation ...) (recur)
  exit-ch nil)

restenb18:11:08

also, does alt! park the calling thread? (blocking-operation ...)here runs inside it's own thread .

restenb18:11:00

(the above code works, I'm just not sure I'm getting what I want in terms of not blocking the calling thread with blocking-operation)

Alex Miller (Clojure team)18:11:18

if blocking-operation is truly blocking, then you shouldn't do this in a go-loop at all

restenb18:11:47

well, it's actually a long polling HTTP call, occasionally returning data to be processed. when no data is available, it blocks.

Alex Miller (Clojure team)18:11:15

well if you do that the right number of times, you will block your entire app

ghadi18:11:31

if blocking-operation launches a thread (which returns a channel) that's fine

Alex Miller (Clojure team)18:11:46

yes, that would be fine

restenb18:11:09

yes, blocking-operation launches a (thread ...)

ghadi18:11:23

you're alting over that channel's result, or the exit channel, whichever returns first

restenb18:11:27

cool. and does alt!park or am I eating up one of the go threads as well?