Rewrote annotations section of tour #756
Conversation
| A simple annotation clause has the form `@C` or `@C(a1, .., an)`. Here, `C` is a constructor of a class `C`, which must conform to the class `scala.Annotation`. All given constructor arguments `a1, .., an` must be constant expressions (i.e., expressions on numeral literals, strings, class literals, Java enumerations and one-dimensional arrays of them). | ||
| hello | ||
| ``` | ||
| This will compile but the compiler will print a warning: "there was one deprecation warning |
There was a problem hiding this comment.
I think you could just say "print a deprecation warning", the exact error wording isn't important
| private val in = new BufferedReader(new FileReader(fname)) | ||
| @throws(classOf[IOException]) | ||
| def read() = in.read() | ||
| ## Annotations that ensure correctness of encodings |
There was a problem hiding this comment.
maybe just "Annotations ensuring correctness" (maybe "enforcing" instead of "ensuring"?)
| @throws(classOf[IOException]) | ||
| def read() = in.read() | ||
| ## Annotations that ensure correctness of encodings | ||
| Certain annotations will actually cause compilation to fail if a condition(s) is not met. For example, the annotation `@tailrec` ensures that a method is [tail-recursive](https://en.wikipedia.org/wiki/Tail_call). Tail-recursion can keep memory requirements constant. Here's how it's used in a method which calculates the factorial: |
There was a problem hiding this comment.
in place of "Tail-recursion can keep memory requirements constant", I would suggest: "Tail-cail optimization prevents tail-recursive code from consuming stack".
| Certain annotations will actually cause compilation to fail if a condition(s) is not met. For example, the annotation `@tailrec` ensures that a method is [tail-recursive](https://en.wikipedia.org/wiki/Tail_call). Tail-recursion can keep memory requirements constant. Here's how it's used in a method which calculates the factorial: | ||
| ```tut | ||
| def factorial(x: Int): Int = { | ||
|
|
|
|
||
| @tailrec | ||
| def factorialHelper(x: Int, accumulator: Int): Int = { | ||
| if (x == 1) accumulator else factorialHelper(x - 1, accumulator * x) |
There was a problem hiding this comment.
if/else on a single line is hard to read IMO. also, the curly braces around the method body can be omitted.
There was a problem hiding this comment.
I would suggest x <= 1 instead of x == 1. 0! is 1 (source).
| def factorial(x: Int): Int = { | ||
|
|
||
| @tailrec | ||
| def factorialHelper(x: Int, accumulator: Int): Int = { |
There was a problem hiding this comment.
since the method is nested, I'd suggest simply helper over factorialHelper
|
|
||
| The following Java program prints out the contents of the file whose name is passed as the first argument to the `main` method. | ||
|
|
||
| The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: |
There was a problem hiding this comment.
"has the @tailrec" should be either "has @tailrec" or "has the @tailrec annotation", according to taste
| 1 error | ||
| ``` | ||
| ## Annotations affecting code generation | ||
| Some annotations like `@inline` affect the generated code. (e.g. your jar file might have different bytes than if you hadn't used the annotation). Inlining code means that the compiler finds the calls to a function definition and moves the body of the function to all the places where the method is called. This can increase performance but also increase the size of the generated code. Using the annotation `@inline` does not ensure that a method will be inlined, but it will cause the compiler to do it iff some heuristics about the size of the generated code are met. |
There was a problem hiding this comment.
is "iff" a typo here, or do you mean "if and only if"?
There was a problem hiding this comment.
for the middle two sentences, I suggest: "Inlining means inserting the code in a method's body at the call site. The resulting bytecode is longer, but hopefully runs faster."
| **Note:** Make sure you use the `-target:jvm-1.5` option with Java annotations. | ||
|
|
||
| Java 1.5 introduced user-defined metadata in the form of [annotations](http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html). A key feature of annotations is that they rely on specifying name-value pairs to initialize their elements. For instance, if we need an annotation to track the source of some class we might define it as | ||
| Java 1.5 introduced user-defined metadata in the form of [annotations](https://docs.oracle.com/javase/tutorial/java/annotations/). A key feature of annotations is that they rely on specifying name-value pairs to initialize their elements. For instance, if we need an annotation to track the source of some class we might define it as |
There was a problem hiding this comment.
I'd suggest replacing "Java 1.5 introduced" with "Java has" or "Java also has" — the introduction is now ancient history.
|
|
||
| ### Java Annotations ### | ||
| This section is for Java developers. |
There was a problem hiding this comment.
This needs expansion and explanation, in my opinion. If it's for Java developers, what's it doing here? In what situation would a Java developer care about this? Does it have to do a particular kind of Java/Scala interop, or what? I'd suggest stating this up front.
travissarles
force-pushed
the
annotations
branch
3 times, most recently
from
11dd30a to
c0b5bfc
Compare
| Annotations associate meta-information with definitions. | ||
| Annotations associate meta-information with definitions. For example, the annotation `@deprecated` before a method causes the compiler to print a warning if the method is used. | ||
| ```tut:fail | ||
| object DepricationDemo extends App { |
travissarles
force-pushed
the
annotations
branch
from
c0b5bfc to
70080cb
Compare
No description provided.