Dart 2 changes to the language tour #677

kwalrath · 2018-03-15T23:53:01Z

Contributes to #507. Staged at:

https://kw-www-dartlang-1.firebaseapp.com/guides/language/language-tour

Even though this page isn't completely done, if it's acceptable I'd like to commit and iterate.

Contributes to #507

chalin

Great changes! Please see inlined comments.

chalin · 2018-03-16T09:56:59Z

examples/misc/lib/language_tour/built_in_types.dart

@@ -6,8 +6,6 @@ void miscDeclAnalyzedButNotTested() {
    // #docregion integer-literals
    int x = 1;
    int hex = 0xDEADBEEF;
-    // ignore_for_file: 2, integer_literal_out_of_range
-    int bigInt = 34653465834652437659238476592374958739845729;


[No action necessary] We should document BigInt somewhere under "Libraries". I've added a bullet to our meta issue #637.

chalin · 2018-03-16T10:00:21Z

src/_guides/language/language-tour.md

+such as type safety, optional `new` and `const`,
+and changes to assertion support.
+</div>
+


There is an alert a few lines below that mentions using Dartpad. We should probably comment that out until Dartpad catches up.

chalin · 2018-03-16T10:08:28Z

src/_guides/language/language-tour.md

-    Alternatively, use /\* ... \*/. For details, see
-    [Comments](#comments).
+:   A way to make Dart ignore some content.
+    For more information, see [Comments](#comments).


How about making this entry consistent with the ones that follow, something like:

A single-line comment. Dart also supports multi-line and document comments. See Comments for details.

chalin · 2018-03-16T10:11:50Z

src/_guides/language/language-tour.md

-:   A type. Some of the other built-in types are String, int, and bool.
+:   A type. A `num` variable's value can be either an `int` or a
+    `double` object.
+    Some of the other built-in types are `String`, `List`, and `bool`.


I'd suggest that we use int to illustrate a type (in the prose here and the code excerpt at the start of this section. That way we can simplify this entry to read:

int

: A type. Some of the other built-in types are String, List, and bool.

Also, it would align more closely to the prose, a little further below, of number being inferred as an int.

Yeah, I struggled with whether to change this. I wasn't sure why we used num in the first place.

I think that maybe we saw JavaScript programmers using no type when they should've used num. With type safety, that shouldn't be as much of an issue.

/cc @sethladd in case his memory is better.

I'm renaming the function printInteger and changing the type to int.

works for me! :)

chalin · 2018-03-16T10:14:44Z

src/_guides/language/language-tour.md

-    in development, rather than at runtime. Strong mode is optional in
-    Dart 1.x, but not optional in [Dart 2](/dart-2).
+-   Although Dart is strongly typed, type annotations are optional
+    because Dart can often infer the type. In the code above, `number`


--> because Dart can infer types.

chalin · 2018-03-16T11:04:11Z

src/_guides/language/language-tour.md

-
-{% include optional-types-2.0.html %}
+Generics are often required for type safety, but they have other benefits
+than just allowing your code to run:


other benefits --> more benefits
(otherwise the rest of the sentence doesn't work)

chalin · 2018-03-16T11:05:17Z

src/_guides/language/language-tour.md

 the list is probably a mistake. Here’s an example:

 <?code-excerpt "misc/test/language_tour/generics_test.dart (why-generics)"?>
 {% prettify dart %}
 var names = new List<String>();
 names.addAll(['Seth', 'Kathy', 'Lars']);
-names.add(42); // Fails in checked mode (succeeds in production mode).
+names.add(42); // Error.


[nit] Drop the period:

// Error. --> // Error

(I believe that this change was only done in this file, not the original source.)

chalin · 2018-03-16T11:24:37Z

src/_guides/language/language-tour.md

+{% comment %}
+TODO: Confirm that non-SomeBaseClass is an error.
+Perhaps be more specific.
+{% endcomment %}


I confirm that it is an error: 'Object' doesn't extend 'SomeBaseClass'. I'd suggest pulling var objectFoo = new Foo<Object>(); out into it's own excerpt, uncommented, so that we can have the analyzer validate our claim that it is an error.

Would you like for me to make that change in this, or maybe a followup, PR?

If you'd like we can have the analyzer error automatically inlined in the prose (as we've done elsewhere in the docs), but I don't think that is necessary.

Yes, if you could write that test, I'd appreciate it. My test fu isn't great. (I agree we don't need to inline the error.)

Working on the test now.

chalin · 2018-03-16T11:29:11Z

src/_guides/language/language-tour.md

+it doesn't wait for those operations.
+Instead, the async function executes only until it encounters
+its first `await` expression.
+Then it returns a Future object,


[Style nit] Future --> Future

(I'm not sure that we are consistent with this convention. E.g., one of the changes you made early in this page was to use <code> style for String, int, etc. but I don't think that we are systematic about it.)

We aren't consistent. At first I was trying to minimize the use of code font, especially in words that are already capitalized (this was the style at NeXT, but code font keeps creeping in.

chalin · 2018-03-16T11:29:53Z

src/_guides/language/language-tour.md

+Although an async function might perform time-consuming operations,
+it doesn't wait for those operations.
+Instead, the async function executes only until it encounters
+its first `await` expression.


Good note. We should be able to refer the reader to a page with more details. How about using the link to https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20170915.md#synchronous-async-start for now?

googlebot · 2018-03-16T11:43:44Z

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

chalin · 2018-03-16T11:44:32Z

FYI, I've committed a fix for analysis failure (adjusting expected analyzer output).

kwalrath · 2018-03-16T15:10:56Z

Thanks for the review and the commit! I'll update this soon.

sethladd · 2018-03-16T22:07:09Z

Thank you for updating the tour to Dart 2!!

Let us know how we can help advertise it when it's published :)

Also alphabetized the list o' links.

…nguage-tour

kwalrath · 2018-03-16T22:14:38Z

ptal

chalin · 2018-03-16T23:35:13Z

src/_guides/language/language-tour.md

+During development, you can validate inputs by using `assert` in the
+initializer list.
+
+<?code-excerpt "misc/lib/language_tour/classes/extends.dart" replace="/extends|super/[!$&!]/g"?>


This was a superfluous <?code-excerpt?> instruction. I've removed it.

chalin · 2018-03-16T23:39:23Z

Re. #677 (comment): I've added the test; see the last commit. I've had to adjust the prose of that section. It now read as follows:

kwalrath · 2018-03-17T01:28:06Z

LGTM. Thanks, Patrice!

kwalrath added 2 commits March 15, 2018 16:28

Dart 2 changes to language tour

563a0d3

Contributes to #507

Searched for "checked" and "production"

a427e60

kwalrath requested review from chalin and leafpetersen March 15, 2018 23:53

googlebot added the cla: yes Contributor has signed the Contributor License Agreement label Mar 15, 2018

Adjust expected analyzer output

71efc9f

chalin approved these changes Mar 16, 2018

View reviewed changes

googlebot added cla: no Contributor has not signed the Contributor License Agreement and removed cla: yes Contributor has signed the Contributor License Agreement labels Mar 16, 2018

Merge branch 'master' into language-tour

0c04fa8

kwalrath added 2 commits March 16, 2018 15:11

Incorporated Patrice's review comments

c56ad69

Also alphabetized the list o' links.

Merge branch 'language-tour' of github.com:dart-lang/site-www into la…

a569b80

…nguage-tour

Add test illustrating generic type argument error

a895bae

chalin reviewed Mar 16, 2018

View reviewed changes

kwalrath merged commit 4c172f7 into master Mar 17, 2018

kwalrath deleted the language-tour branch March 17, 2018 01:28

kwalrath restored the language-tour branch March 17, 2018 01:32

kwalrath deleted the language-tour branch March 17, 2018 01:33

kwalrath mentioned this pull request Mar 17, 2018

Update language tour for Dart 2 changes #507

Closed

10 tasks

Dart 2 changes to the language tour #677

Dart 2 changes to the language tour #677

Uh oh!

Conversation

kwalrath commented Mar 15, 2018

Uh oh!

chalin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

googlebot commented Mar 16, 2018

Uh oh!

chalin commented Mar 16, 2018

Uh oh!

kwalrath commented Mar 16, 2018

Uh oh!

sethladd commented Mar 16, 2018

Uh oh!

kwalrath commented Mar 16, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chalin commented Mar 16, 2018

Uh oh!

kwalrath commented Mar 17, 2018

Uh oh!

Uh oh!