I still have a bit of difficulty to localize certain topics in the documentation. Consider an example, we look up fold method in the documentation. To this end, we go to Scala Standard Library 2.13.8
and search for fold. This abbreviated definition appears on the right side:
def fold(z: A1)(op: (A1, A1) => A1): A1
for Array and many others. Assume we would like to learn more and click on the field that interests us. Now some extended definition appears
def fold[A1 >: A](z: A1)(op: (A1, A1) => A1): A1
In the text below everything, i.e. A1, z, op, returns except A is explained. So what is A?
Next, I see an unknown for me >: operator. I would like to look it up in the documentation too. A quick search yields
def >:> (that: ClassManifest[_]): Boolean
But that is not what I am looking for. How can I find information on >:?
You cannot hope to find all the syntax/concepts of the language in the documentation.
In the documentation, if you click on the fold entry, it says:
A1 a type parameter for the binary operator, a supertype of A.
So >: means “is a supertype of”.
Here A is the type parameter of the class (in this case Array[A]), and [A1 >: A] means that A1 has to be a supertype of A otherwise the type checker will reject it.
You need to study the Scala language more seriously through a book or an online course, instead of doing a bunch of random web/documentation searches and trying to write a function or two, without fully understanding the language.
That is a far less efficient use of your time. You need to spend some decent amount of time up front, to study the language, which will save you so much more time later on.
For example, your question is explained in Chapter 18 “Type parameterization” of “Programming in Scala 5th Edition”. A1 >: A is called a lower type bound. It is also explained in one of the online courses on Coursera.
Unfortunately I see this type of horrible “learning method” way too often. It’s like everybody is trying to do the absolute bare minimum, so they end up searching for hours and hours on some really basic information about the language.
The SO answer linked from there lists various symbols.
The FAQ also links to a books page which I think does not even cover all of them. You can ask here or on discord for recommendations which someone is obliged to provide more than once a week. Usually two people chime in simultaneously, so they may have programmed a hot key with their favorite books.
The spec is not too forbidding for certain questions.
“You cannot hope to find all the syntax/concepts of the language in the documentation.” --that is the strangest thing I ever heard! Where else should it be found?
While I fully agree with you that one should read a book up front, being able to efficiently search the documentation is equally important. One may use fold sufficiently early in learning the language, it is a strange demand to read all 18 Chapters of the book in order to be able to comprehend the signature of the method.
You really shouldn’t use fold on collections at all, is a weird function.
Rather use foldLeft or foldRight whose documentations are easier to understand.
In any case, the scaladoc is there for knowing which operations are available on the stdlib, not to teach the language; it assumes you know basic elements of syntax beforehand.
He specifically told you the book for the language to read written by the author of the language. I’ve personally read it three times. And I still pick new things up from it on each read through. Scala is a very deep and nuanced language.
I guess it might also be worth adding that with the fifth edition, the book has been split into two volumes, with the second one (covering more advanced concepts) still in the making.
Adding this more for any future readers of this thread.
The problem here is that Scala is documented across multiple forms of documentation.
Intro books to syntax and concepts
The API documentation (where you would find fold)
The spec where you find lots of gory details about parsing and expected behavior
So you, @yarchik, are correct. The answer should be found in the documentation. And @spamegg1 is correct. You cannot hope to find all the syntax/concepts of the language in (all) the documentation.
Programming in Scala, the api docs, and the spec will cover between 80-99% of all your questions. That range is because Scala is a complex topic and like all complex topics the more you learn about it the more things fit in place without extra explanation. The remaining 1% is for user groups like this one because someone will always know a bit of extra information, or be able to explain it in a way that makes sense that you don’t-have/haven’t-learned (and likely vice-versa).