I know @U04V70XH6 has some thoughts on this and there has been a lot of work recently on updating docs at clojure-docs. For example, I believe the docs for jdbc were updated about a month or two back (http://clojure-doc.org/articles/ecosystem/java_jdbc/home.html)

As a beginner I have found Clojure’s documentation overall to be very good

especially

It certainly is possible to find what you’re looking for on clojuredocs. 😃

The user submitted examples help a lot, for sure.

@U05380FG9 the “see also” section has also been tremendously useful to me as a beginner learning clojure.core

It helped me discover many functions

or quickly find functions which I forgot the name of

for example yesterday I remembered there was a function to set the value of an atom but forgot its name. I searched for swap! (which I remember was the function to transform the value of an atom) and looked in see also, which contained reset!, the function I was looking for

a bit of a silly example, but still

There was a discussion about this on the Clojure mailing list

two key takeaways (imo): 1) docs can be separate from code. No reason to tie doc updates to the main clojure distro. 3rd party docs are welcome! 2) Clojure loves data, can we keep it that way? Why not keep all this documentation in a data format (instead of markdown which is not data, but text). Seems like a combination of clojure core specs, doc strings, comments, and proper formatting could do a lot.

the bits are all there, just needs a bit more editor support

link to the mailing list post: https://groups.google.com/forum/#!topic/clojure/8awHqxldZKA

so about that 2nd part, keeping data as data…

I don’t completely understand that point…

doesn’t good documentation necessarily have to be text?

it can be enriched with data, I guess?

@U05380FG9 He means that the system of record should be data -- and then all sorts of tools can generate whatever type of docs them want from that data.

I understand the value of consumable/transformable data… but still… suppose I want to end up with some documentation that looks like this: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector

Most of the main content of that page is straight text and can be represented well as some kind of markup language. How might that be represented with other kinds of data?

I want to help with improving the docs… but I’m honestly having trouble understanding the point being made in the mailing list…

Look at http://clojuredocs.org — http://clojuredocs.org/clojure.core/select-keys — that’s drawn from data: the metadata of all the namespaces and the functions, and some additional data added from a database, entered as examples by community members.

The only thing on that page drawn from the select-keys function is the docstring — and it says Available since 1.0 (from metadata on the function).

Members can contribute to http://clojuredocs.org and members can contribute to http://clojure-doc.org (longer form tutorials and stuff about the ecosystem rather than core Clojure).

In addition to the raw data inherent in the Clojure core code itself (namespaces, symbols, metadata, docstrings), there are also all the core specs which can be used to generate all sorts of additional documentation (folks haven’t done anything with this yet, beyond the updates to the doc function shows specs as well as docstrings).

I want to ask about the core specs stuff… but lemme ask this one first… Is there something wrong with trying to inject more detailed docstrings (maybe in a markup lang) for tools to look up?

And then there’s docstrings in Clojure/core itself which are treated as “code” and therefore need a CA and a patch, rather than a PR.

@U05380FG9 If the docstrings used markup, then all tooling, even the bare bones REPL, would need to deal with it. That’s a bad idea. And that’s why the Clojure/core folks are so against that.

right~ but if we have a separate repository of just “better docstrings”, but community would be able to actively participate in making it better…

The docstrings all end up in the clojure-x.y.z.jar file so that’s another reason for not wanting more detailed docstrings in the code.

add in some tooling to look up docstrings from that alternative source… wouldn’t that work?

Sure, and anyone is welcome to set up a community project with “better docstrings”, in some form that tooling can use (data).

A web site that could yield arbitrary documentation in plain text, markdown, rendered HTML, etc from a GET /clojure/java/jdbc/query?format=… style URL would be great. Any volunteer or group of volunteers could do that, and seed it with the default docstrings until community members edited them.

sounds good 😃

I’ll observe that I moved the java.jdbc docs out of the contrib repo to http://clojure-doc.org specifically to get them out of the CA/patch process and into an open community GitHub/PR process. I did that ages ago. But almost no one has ever contributed to those docs, beyond me and (recently) one other community member.

and thank you for running that project!

Allowing the community to maintain external documentation is one thing — and it’s a good thing — but actually getting people to contribute is something completely different. Lots of people love to complain about the state of Clojure documentation, but when it comes down to actually making it better… crickets 😐

(and since some folks have been complaining about the docs for years now, but community contribution levels remain low, you’ll understand why the Clojure/core folks tend to be a bit unsympathetic to the complaints these days 🙂 )

yeah~ well… working on documentation probably doesn’t seem very appealing to people, unfortunately… but it definitely is necessary…

I looked into clojure.core with the other day. It reports there are 500+ public functions in there. It’s a bit daunting to have to replace that many docstrings.

I value the time the Clojure/core team spend on the code — on Clojure itself and the power it provides us all. I don’t want them to “waste” time on documentation instead. But I’d sure like to see more community members contribute to the various documentation sites.

@U05380FG9 You’d generate an initial version from the default docstrings in the core — not much effort — and then provide an editing mechanism for the community to expand those. It would be a slow, incremental replacement over time.

That’s pretty much what http://clojuredocs.org does.

I actually hacked together something that will highjack CIDER’s doc requests and inject it with new docstrings if available…

it’s not fancy and it’s not a web service… but I guess it’s a start…

https://github.com/Odie/sidedocs-nrepl

back to the core lib specs you mentioned earlier…

has the core lib been spec’ed? where can I get a hold of that?

https://github.com/clojure/core.specs.alpha — mostly macros right now I think — that’s part of Clojure 1.9 alphas (we have Alpha 20 in production).

okay~ having any kind of type info on the function params would help a whole lot. I can’t remember the number of times when I wondered “what kind of stuff will that function actually accept?”

Being able to play with the function in the repl definitely helps. But, that seems to introduce unnecessary friction into the dev process and is likely to penalize newcomers to the language.

Will look into generating function param documentation using core.specs.alpha. 😃

looked at Racket’s api docs the other day… https://docs.racket-lang.org/collections/collections-api.html It’s rather nice that each function’s prototype is clearly outlined above any additional explanation.

I guess instead of “prototype”, I should say, function signature…

I guess I’ve gotten used to just pressing ctrl-alt-, d when I want to see docs (inline, in ProtoREPL). I tend to only have a few lines of the REPL open at the bottom of the screen and do everything in files and have ProtoREPL display inline results in the editor. I’ve also gotten used to Clojure’s “lack of types” so there are a lot of functions you don’t really need to know “what kind of stuff” they will accept, if they’re written for a sequence, for example.

yeah~ I like the lack of strict types and the flexibility that comes with it. Still, when I first get acquainted with an api/function, it can get a little confusing.

For example, the api docs for ‘ns-publics’ says: ------------------------- clojure.core/ns-publics ([ns]) Returns a map of the public intern mappings for the namespace.

at first glance, I have no idea what it actually accepts…

do I pass it a string? do I somehow lookup an ‘ns’ (as the param name suggest) first?

oh, I can just pass it a symbol?

yeah~ The repl is very good for exploring an api. But, I think a little clarity in the docs will go a long way.

For webserver, ring has reload middleware https://github.com/ring-clojure/ring/wiki/Reloading. But I would suggest you to reload manually with help from tools like https://github.com/weavejester/reloaded.repl or https://github.com/weavejester/integrant-repl

You might also want to take a look at https://github.com/danielsz/holygrail

it’s got a setup where it’ll refresh your repl automatically on file save… it helps to keep your repl in the same state as your source file…

if you use boot there is a watch task.

How about just using something like name#?

seems good, although it seems more like variable defined in a macro

calling it name is valid, but you can also qualify it, as in foo-name (where I can’t guess foo’s real name without knowing more about your code)

defrecord already has ILookup

But the idea was to make a “recyclable” type, where there are mutable fields behind the scenes, and the ILookup would return the current value, not whatever mutable container that held that value

gross 😉

I'm at the point where GC thrashing is my biggest issue. Time to try out gross stuff 😛

Clojure, being a Lisp, allows - in symbol names. Java, the compiled target host environment, does not. So when Clojure compiles com.pay.test-utils.helpers, it produces a Java package com.pay.test_utils containing a class helpers. The file system must conform to Jaya's view of packages so it must be com/pay/test_utils on the file system. Does that answer your question?