Hi,

i had to revisit some code i had written on top of the spec module, and
it took more effort than i would have expected. And I think the problem
is not entirely coming from my code ;)

I feel that the term "spec" is used for several, and as I understand
them, different things within the spec module, that I find easily
confusing.

It seems to me that the general meaning of "spec" is "anything we can
match() a value against". And this may therefore be:

a) any literal value, e.g. None, 1 'abc',  
b) any type, e.g. int, str, class X.
c) any instance of a sub-class of the SpecOperator, including in
particular ConnectiveSpecOperator
d) any instance of the free-floating Anything class.
e) any instance of the Specification class, that is a
"documention-added wrapper" of specs as defined in (a) to (d).
f) the additional alternative shorthand for (e) in the form of a
spec(spec, *docs) function, that thus returns an instance as in (e),
Specification(spec, '\n'.joins(docs))
g) similar as (f) for the nspec(spec, *docs) function

I think it makes sense to have a collective but clear term for any of
the things identified in (a) to (d). A nice thing about (a) and (b) is
that these are nothing "special". the spec module does nothing to make
them "specs". They are not marked as specs in any way, except by the
fact of using them as specs.
Those in (c) are marked as being instances of a specific Class. As for
(d), not sure why this class is not a subclass of SpecOperator? This
collection is therefore referred to interchangedly as SpecOperators or
as "specs".

For (e) to (g), that return a "Specification", but are otherwise also
referred to as "spec". While the Specificition and SpecOperator classes
seem to overlap conceptually --- e.g. they are both callable, to give a
nice way to match() against them -- they are indepedendent classes as
they do not share same inheritance.

The term "spec" or "Specification" makes me think naturally of the (e)
category, i.e. of Specification -- instances know about themselves,
their doc, how to self format, etc.

While, those from (a) to (d) make me think more of "an arrangement of
Types and/or Values", a "genetic pattern" to compare values against.
The term "specimen", to stay with the same root terminology, comes to
mind, but i think more of these as "typograms" or "valuegrams".

Does anyone share this feeling of confusion? Not sure what changes to
make to improve clarity, but i think at least the usage of the term
"spec" should be reserved either for "typograms" or for
"Specifications", but not for both.

mario