Upon further investigation, there are helpful examples on this page
http://clojure.org/guides/spec, which was mentioned in the 1.9.0-alpha1
release notice, and there's a small example near the end of the Rationale
and Overview page. I still feel as if both pages kind of start in the
middle rather than at the beginning by going over the guts before their
purpose, but the guides page gets to the point fairly quickly. I still
think the "species" etymology and def is unhelpful, even though in some
sense it's just the sort of thing I would like in a different context.
Thanks again, in any event.
On Wednesday, May 25, 2016 at 11:14:59 AM UTC-5, Mars0i wrote:
>
> 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 clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
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 clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
