tag and ref mentioned but not (yet?) explained

[randomstep]

The Expressions | Partial Application part of the tutorial mentions that certain things return a tag or a val. There is a caveat repeated twice about wrapping the return value if you need a reference type. However nothing has yet explained the reference type idea (I don't think), nor the tag type. It would be great if there was a link to more information.

[andymcn]

'tag' and 'ref' are capabilities, which are explained in the Capabilities | Reference Capabilities section.

Possibly we need to put in a reference to that section from elsewhere, such as Expressions | Partial Application. That might end up being a lot of references, since capabilties are fairly funadmental to the language and are mentioned in a lot of places.

Maybe keywords etc should be made into links to the part of the tutorial where they are explained.

Thoughts anyone?

[sblessing]

Making keywords to links might be the way to go. However, is this is the only place where this happens, should capabilities be explained earlier?

[randomstep]

I know I've been wondering about capabilities since they were hinted at early on. I'm just about to read that section, so no idea yet if it is possible to explain them earlier, or if some short explanation would suffice until readers get to the capability section.

[randomstep]

"If you've used C/C++, you may be familiar with const, which is a type qualifier that tells the compiler not to allow the programmer to mutate something.

A reference capability is a form of type qualifier and provides a lot more guarantees than const does!"

Perhaps this should be at the beginning - this is the first time I've really started to get excited and understand a bit what capabilities really mean.

[JobLeonard]

Hey, I discovered Pony through the Curry On! Video, and I'm working my way through the tutorial. I was about to open the same issue as this one, so I think it's a common point of confusion for readers ;). Even though in general these tutorials have very accessible and concise explanations, by the way.

I think mentioning that they will be explained later would also clarify. The tutorial has more of these moments, for example when discussing ephemeral types, you talk about consuming variables:

In Pony, every expression has a type. So what's the type of consume a?

But consuming variables won't be explained until the next page! So I the question threw me off quite a bit, wondering if I missed anything.

I think that part of the tutorial would flow much better if the "Consume & Destructive Read" sections would be wedged between "What Counts as an Alias" and "Ephemeral Types".

Also, I'm just hitting the sections on capabilities, and it really feels like they could be conceptually introduced a bit earlier. At least the Object/Reference capabilities and Guarantees sections. They don't feel that hard to grok at all. Plus, it's the capabilities that make Pony exciting, like randomstep says! Hook people as early as possible!

[andymcn]

Thanks for the feedback. We've been pretty busy recently (and still are) so I'm afraid we've neglected the tutorial a bit, sorry. We will get round to it soon, so please keep the complaints and suggestions comming, they are very useful.

[JobLeonard]

Also, this "show what happens without explaining why until later"-style of writing pervades the tutorial on the small scale too, and in all honesty it get's a bit annoying because I keep trying to make sense of something I cannot make sense of yet. For example, this was pretty much my thought process when I got to this section:

What does this look like?

recover Array[String] end

That's a simple one: it returns an Array[String] iso, instead of the usual Array[String] ref you would get.

"Why? Why does it return this? I mean you're not even saying what recover should return! Does it default to iso? Is that it?"

Here's a more complicate example from the standard library:

recover
  var s = String((prec' + 1).max(width.max(31)))
 var value = x

 try
   if value == 0 then
     s.push(table(0))
   else
     while value != 0 do
       let index = (value = value / base) - (value * base)
       s.push(table(index))
     end
   end
 end

 s.append(typestring)
 _extend_digits(s, prec')
 s.append(prestring)
 _pad(s, width, align, fill)
 s
end

That's from ToString. It creates a String ref, does a bunch of stuff with it, and finally returns it as a String iso.

"Yeah, ok, but why an iso? I got two unspecified samples resulting in iso now, but that's still no guarantee you know!"

Both of those examples use the default reference capability for a recover expression, since they don't specify one. The default for any mutable reference capability is iso and the default for any immutable reference capability is val.

"Ok, finally! Why didn't you just open the paragraph with something like "if you don't specify a capability, Pony will use a default one. The default for any mutable reference capability is iso and the default for any immutable reference capability is val" and then show me these examples?!"

I hope I don't come across as hostile - I'm actually really enjoying what I see about Pony so far, and again: in general the tutorial is concise and clear. I think most of the confusion stems from the order in which things are introduced.