ILLER EPFL · 2011-07-20 · Marc Weil Jamie Allen Daniel Sobral Josh Marcus Donald McLean David...
46
Heather MILLER, EPFL Scala DOCUMENTATION 1 Official Saturday, July 16, 2011
Transcript of ILLER EPFL · 2011-07-20 · Marc Weil Jamie Allen Daniel Sobral Josh Marcus Donald McLean David...
Heather MILLER, EPFL
ScalaDOCUMENTATION
1
Official
Saturday, July 16, 2011
Good documentation is important.
2
Saturday, July 16, 2011
Good documentation is important.
2
REALLY
V
Saturday, July 16, 2011
Good documentation is important.
2
is a huge issue.
Saturday, July 16, 2011
3
Saturday, July 16, 2011
3
Saturday, July 16, 2011
4
Saturday, July 16, 2011
There are a bunch of holes in the API.
5
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
The documentation problem hurts adoption.
6
Scala is known for attracting advanced coders.
Advanced coders often aren’t afraid to dig into source code to find answers.
But a lot of other interested newcomers and potential adopters are.
This is one of those things that isn’t totally obvious to the bulk of the community...
Good documentation is what fills the gaps.
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 7
If you want to make a meaningful contribution...
The easiest and most meaningful way to contribute to Scala is through documentation.
If you work on documentation this weekend, you'll affect the most people possible- the entire community here today, as well as countless others using the language all over the world.
*
*
Saturday, July 16, 2011
Good documentation is important.
8
Saturday, July 16, 2011
Good documentation is important.
8
For all of us.
Saturday, July 16, 2011
9
ScalaDOCSPREE
the
Saturday, July 16, 2011
First... a huge thanks
Saturday, July 16, 2011
Marc WeilJamie Allen
Daniel Sobral
Josh MarcusDonald McLean
David Esterkin
Chris LeagueRoland Kuhn
Iain McGin
Greg Price
Seth Tisue
Erik Osheim
First... a huge thanks
Paul Phillips
Saturday, July 16, 2011
There are now something like
15freshly documented entities in nightly.
Saturday, July 16, 2011
FutureDOCUMENTATION
the
12
of
Saturday, July 16, 2011
Two Types of Efforts.
API-style Article/Guide-style.
Official API
TUTORIALS
...stuff that is longer, more high-level, and
example-rich
GUIDESProgramming
OVERVIEWS
...stuff that is more concise, lower-level, and
the most detailed.
Saturday, July 16, 2011
Two Types of Efforts.
API-style Article/Guide-style.
Official API
TUTORIALS
...stuff that is longer, more high-level, and
example-rich
SCALADOCCOLLADOC
GUIDESProgramming
OVERVIEWS
...stuff that is more concise, lower-level, and
the most detailed.
Saturday, July 16, 2011
Two Types of Efforts.
API-style Article/Guide-style.
Official API
TUTORIALS
...stuff that is longer, more high-level, and
example-rich
SCALADOCCOLLADOC
SOME NEW IDEAS...(later in talk)
GUIDESProgramming
OVERVIEWS
...stuff that is more concise, lower-level, and
the most detailed.
Saturday, July 16, 2011
Two Types of Efforts.
API-style Article/Guide-style.
Official API
TUTORIALS
...stuff that is longer, more high-level, and
example-rich
SCALADOCCOLLADOC
SOME NEW IDEAS...(later in talk)
GUIDESProgramming
OVERVIEWS
...stuff that is more concise, lower-level, and
the most detailed.
both should be easy to contribute to.GOAL:
Saturday, July 16, 2011
API-style docs.
14
Saturday, July 16, 2011
API-style docs.
14
Contributing toV
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 15
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 15
fork
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 16
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
add doc comments
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 18
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 18
pull
Saturday, July 16, 2011
Guide-style docs.
19
Saturday, July 16, 2011
20
Saturday, July 16, 2011
21
Saturday, July 16, 2011
22
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 23
Scala By Example
DRAFTMay 11, 2011
Martin Odersky
PROGRAMMING METHODS LABORATORY
EPFLSWITZERLAND
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Scala 2.8 Arrays
Martin Odersky, EPFL
October 1, 2009
The Problem
Arrays have turned out to be one of the trickiest concepts to get right in Scala. This has mostly to dowith very hard constraints that clash with what’s desirable. On the one hand, we want to use arrays forinteroperation with Java, which means that they need to have the same representation as in Java. Thislow-level representation is also useful to get high performance out of arrays. But on the other hand, arraysin Java are severely limited.
First, there’s actually not a single array type representation in Java but nine different ones: One rep-resentation for arrays of reference type and another eight for arrays of each of the primitive types byte,char, short, int, long, float, double, and boolean. There is no common type for these different rep-resentations which is more specific than just java.lang.Object, even though there are some reflectivemethods to deal with arrays of arbitrary type in java.lang.reflect.Array. Second, there’s no way to cre-ate an array of a generic type; only monomorphic array creations are allowed. Third, the only operationssupported by arrays are indexing, updates, and get length.
Contrast this with what we would like to have in Scala: Arrays should slot into the collections hierar-chy, supporting the hundred or so methods that are defined on sequences. And they should certainly begeneric, so that one can create an Array[T] where T is a type variable.
The Past
How to combine these desirables with the representation restrictions imposed by Java interoperabilityand performance? There’s no easy answer, and I believe we got it wrong the first time when we designedScala. The Scala language up to 2.7.x “magically” wrapped and unwrapped arrays when required in aprocess called boxing and unboxing, similarly to what is done to treat primitive numeric types as ob-jects. “Magically” means: the compiler generated code to do so based on the static types of expressions.Additional magic made generic array creation work. An expression like new Array[T] where T is a typeparameter was converted to new BoxedAnyArray[T]. BoxedAnyArray was a special wrapper class whichchanged its representation depending on the type of the concrete Java array to which it was cast. This
1
24
Saturday, July 16, 2011
25
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv 26
The idea...
The idea is to produce a resource that is official and up-to-date.
The go-to for non-API-style documentation.
Will live on github, so community contributions can be made official!
A growing doc.
Saturday, July 16, 2011
How-tosCONTRIBUTING
27
of
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing to the API is becoming really easy.
28
Thanks to the [in-progress] git move.
Make your edits.
Submit a pull-request.
(http://goo.gl/sb8Mv)
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing to the API is becoming really easy.
28
Thanks to the [in-progress] git move.
Fork the official Scala github repo.1.Make your edits.
Submit a pull-request.
(http://goo.gl/sb8Mv)
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing to the API is becoming really easy.
28
Thanks to the [in-progress] git move.
Fork the official Scala github repo.1.Make your edits.2.Submit a pull-request.
(http://goo.gl/sb8Mv)
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing to the API is becoming really easy.
28
Thanks to the [in-progress] git move.
Fork the official Scala github repo.1.Make your edits.2.Submit a pull-request.3.
(http://goo.gl/sb8Mv)
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing to the API is becoming really easy.
28
Thanks to the [in-progress] git move.
Fork the official Scala github repo.1.Make your edits.2.Submit a pull-request.3.
Detailed instructions on the wiki!!(http://goo.gl/sb8Mv)
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing Guide-style docs...
29
Talk to me!
There will be a directory structure in a guide-doc repository on github.
The idea...
Pull-requests to accept new docs.
Accepted docs go live in one organized place, should be up-to-date.
Saturday, July 16, 2011
| Scalathon, Philadelphia PA. July 15-17, 2011. http://goo.gl/sb8Mv
Contributing Guide-style docs...
29
Talk to me!
There will be a directory structure in a guide-doc repository on github.
The idea...
Pull-requests to accept new docs.
Accepted docs go live in one organized place, should be up-to-date.
inreStructuredText( )
Saturday, July 16, 2011
Thanks.QUESTIONS?
30
Saturday, July 16, 2011
