<div dir="ltr"><div><div>I think you have reiterated what I said: what does this mean? I worked out myself that the first form:<br><br><span class="gmail-im">-type atom(X) :: list(X).<br><br></span></div><span class="gmail-im">works as the pre-defined types are not "reserved words" in any sense. BUT THIS IS NOT STATED IN THE DOCUMENTATION. I discovered it by looking at the what the parser output.<br><br></span></div><div><span class="gmail-im">So I continued to look in the parser to see if there were more things which are allowed but not documented and I found the second two (plus more). So my question was what do they mean? While my examples may be erroneous does this syntax have any possible meaning at all? You seem to imply that it doesn't. If not why is is there at all? Was someone just having a wild time chucking in whatever they could dream up? And it if can be used in a meaningful way why isn't it documented? I think that having syntax which can never legal is a great way to complicate things. Which we don't need.<br><br></span></div><div><span class="gmail-im">I quite agree that semantics is the important thing but we need syntax to express ourselves. And if the documentation doesn't cover all the legal syntax then all legal syntax might have a meaning so it is reasonable to ask what it means.<br><br></span></div><div><span class="gmail-im">So my suggestion is that the documentation should cover all legal type syntax. And that we should remove all syntax which can never be legal.<br><br></span></div><div><span class="gmail-im">Robert<br><br></span></div><span class="gmail-im"></span></div><div class="gmail_extra"><br><div class="gmail_quote">On 2 October 2016 at 20:42, Kostis Sagonas <span dir="ltr"><<a href="mailto:kostis@cs.ntua.gr" target="_blank">kostis@cs.ntua.gr</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 10/02/2016 12:56 AM, Robert Virding wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Is there any better documentation of type defs and specs than that which<br>
occurs in the Erlang Reference manual? If so where is it?<br>
</blockquote>
<br></span>
In light of recent discussions on this mailing list, I wish that those who complain about documentation took a bit of time to tell us which aspects of the current documentation they find unsatisfactory and why.<br>
<br>
It's very difficult to know how to make something "better" if one does not get told why it's not good enough as it is.<span class=""><br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I am trying to define an equivalent type/spec syntax for LFE so I am<br>
going through the valid syntax then trying to work out what they mean.<br>
</blockquote>
<br></span>
OK, here is a thing I try hard to teach students who take my compiler courses: Do NOT mix up in your mind(s) syntax and semantics of a language. They are certainly not the same thing; they may not even be related in any way.<br>
<br>
So it's not particularly surprising that you cannot "work out what they mean" by looking at the valid syntax of types and specs.<span class=""><br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
And there is a lot of strangeness from simple things like the predefined<br>
type names are 'reserved' so this is valid:<br>
<br>
-type atom(X) :: list(X).<br>
<br>
(whatever it means) to much more strange things like:<br>
<br>
-spec foo(Y) -> integer() when atom(Y).<br>
-spec foo(Y) -> integer() when atom(Y :: integer()).<br>
<br>
(whatever they mean) neither of which are mentioned in the docs.<br>
</blockquote>
<br></span>
First of all, why should the above be mentioned in the reference manual, especially if they are "strange"?<br>
<br>
Second, why do you find the first of these examples strange?  Erlang has been designed so that e.g. functions do not have just some alphanumeric sequence of characters as a name but their name includes an arity.  This means that length/1 is reserved (you cannot redefine it), while length/3 is not.<br>
<br>
In this prism, why do you find it strange that the atom/1 type is not? (Only atom/0 is.)<br>
<br>
<br>
As to what the above examples mean, well it's very simple:<br>
<br>
 - The type declaration defines a polymorphic type called atom that is an alias for the built-in polymorphic type list.  Granted that it's a very stupid name for this type, but there is nothing that forces good naming convensions in Erlang.  I can certainly define a length/3 function that takes integer() arguments and returns a binary() of some sort.<br>
<br>
 - The first foo/1 spec has no meaning because you cannot use the atom/1 type as a subtype constraint.  In fact, if you put this spec in a file and try to compile it, you will get a warning, which is consistent with the (very bad IMO) philosophy of the Erlang compiler to not refuse to compule code which is damn stupid.  If you use dialyzer on this spec, you will discover that this tool is more sane as far as tolerating constructs which have no meaning.  You will get a dialyzer error in this case.<br>
<br>
 - The second foo/1 spec is rejected even by the compiler.  Have you actually tried this and the compiler accepted it?<span class=""><br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
So is there a more complete and understandable documentation some where?<br>
</blockquote>
<br></span>
Suggestions on how to make the current documentation more complete and understandable are welcome!<span class="HOEnZb"><font color="#888888"><br>
<br>
Kostis<br>
</font></span></blockquote></div><br></div>