Re: Clojure core documentation

Alex Miller writes: > On Monday, September 25, 2017 at 11:42:12 AM UTC-5, Phillip Lord wrote: >> Clojure's doc strings, though, contain knowledge that is not >> clear. Consider, this documentation: >> >> Returns a new seq where x is the first element and seq is the rest. >> >> x is the name of

Re: Clojure core documentation

Hi Alex, Thank you for the work you've already put in to improving docstrings in Clojure 1.9, I noticed a bunch of docstring Jiras land recently which is really encouraging. Specs certainly helps those of us who are familiar with Clojure and clojure.spec already, and know how to use specs to g

Re: Clojure core documentation

If the docstring were more structured (either using conventions within the docstring, or additional metadata elements on the var), then this would not be a problem. First line for tooltip, main doc for hover-over, examples on request, that kind of thing. Phil Beau Fabry writes: > As a docstrin

Re: Clojure core documentation

At first I thought the doc was really complicated and hard to understand, and then I became more familiar with FP and Clojure, and now I think the doc is perfect, sweet, short and to the point. What happens with a lot of those higher order functions is that you really don't understand them unti

Re: Clojure core documentation

On Monday, September 25, 2017 at 11:42:12 AM UTC-5, Phillip Lord wrote: > > > > Clojure's doc strings, though, contain knowledge that is not > clear. Consider, this documentation: > > Returns a new seq where x is the first element and seq is the rest. > > x is the name of a parameter. So is th

Re: Clojure core documentation

As a docstring I don't find this superior. Docstrings (for me) are usually viewed as quick little pop-up boxes in my editor. The existing clojure docstring for `apply` gives me the information I need much faster and with less screen real estate. YMMV. On Monday, September 25, 2017 at 9:42:12 AM

Re: Clojure core documentation

Clojure's doc strings, though, contain knowledge that is not clear. Consider, this documentation: Returns a new seq where x is the first element and seq is the rest. x is the name of a parameter. So is the the second occurence of seq, but not the first. Neither first, nor rest refer to the func

Re: Clojure core documentation

Clojure has great data, and great metadata. Documentation strings are *not* great data, they are strings. If you want to provide more structured support than docstrings to help someone use Clojure, look at specs for inspiration. They are made of data, and they live in a registry separate from Cloj

Re: Clojure core documentation

I am not convinced I would have found the API docs on reducers or zippers more informative if all references had been tidily markdown'ed. The new clojure.org welcomes contributions of topical overviews. That's helpful. But, to interpret docstrings, nothing helps like perspective. The thing a

Re: Clojure core documentation

Yeah, I saw the same video and wanted to do something to start help improving the documentation also. I remember the time when I was trying to get into clojure. It was hard to make heads or tails out of the official api docs. Regarding the syntactic format of the documentation, wouldn't somethi

Re: Clojure core documentation

The question of markup has tended to attract many far-sighted suggestions that turn it into a bike shed. Luckily, the undertaking needs no blessing. Clojure's doc strings change infrequently, if ever! Someone may set forth a markup language and create a fork with marked-up doc strings, and tool

Clojure core documentation

Hi, I apologise if this is not the appropriate forum, but please bear with me. Having watched Bozhidars Clojutre presentation, https://www.youtube.com/watch?v=nrpsMB2gYI0&index=2&list=PLetHPRQvX4a9iZk-buMQfdxZm72UnP3C9