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
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
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
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
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
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
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
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
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
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
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
11 matches
Mail list logo
