I'm very happy about clojure.spec. I think. (!)
Two suggestions for the documentation page. Just my two cents.
First, it would be helpful to begin with a description of what clojure.spec
does and how it will be used, and one or two brief examples right at the
beginning--ideally before the first or second page scroll. The current
"Rationale and Overview" page starts with a very long rationale section
("Problems", "Objectives", "Guidelines"), followed by a long and detailed
"Features" section. Both of these are needed, but throughout the rationale
material, I was trying to infer what it was that clojure.spec really was,
and then when I got to "Features", I still was trying to get a general
sense of how clojure.spec supposed to be used before wading through an
informal specification of its details. No doubt I can study "Features" and
synthesize my own general understanding of clojure.spec, but I don't think
that should be necessary. (When I say, "how it is used", I don't mean how
it will interact with clojure.test. That's important but secondary. I
need something more fundamental.) The many postings in this thread show
that many people already have the idea. I assume that this is either
because they've already worked with something similar, or did have the time
to closely study the documentation and synthesize their own understanding,
or maybe they're just smarter than I am. :-)
2. This is just confusing:
Communication
Species - appearance, form, sort, kind, equivalent to spec (ere) to look,
regard
+ -iēs abstract noun suffix
Specify - species + -ficus -fic (make)
A specification is about how something 'looks', but is, most importantly,
something that is looked at. Specs should be readable, composed of 'words'
(predicate functions) programmers are already using, and integrated in
documentation.
I gather that the indented part is excerpted from a dictionary entry for
the word "Species", but at first I thought it was an example or a part of
the specification of clojure.spec. Just wasn't sure. Coming as it does in
a section called "Communication", and followed by text that includes "Specs
should be readable"--when the "example" isn't readable, it's very
confusing. Cute, maybe, once you understand it, but unhelpful for someone
who is trying to learn what clojure.spec is.
Thanks! I still am not entirely clear about how clojure.spec should be
used, but from what I can tell, it's very good thing and I'm very happy
about it.
I was a participant in a few long discussions about improving Clojure
docstrings, and I gather that clojure.spec might supplement or end up
playing a role in modifying docstrings to provide succinct, clear
descriptions of expected arguments, with potentially systematic display
formatting, all of which would be great. The other uses of clojure.spec,
at least as I understand them, also seem extremely useful.
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/d/optout.
