Docs: various errors in language/library tour, synonyms article, style guide

[nicolasgarnier]

From ivo.balbaert on July 17, 2012 11:19:47

Hi, congratulations with the new Dart website, it was already good, now it is even more enjoyable!

I have recently gone through the tours and some articles, testing programs as I went along, and discovered the following small errors (I verified they are still present in the new website version). I run on Windows 7 Professional - 64bit - Dart SDK/Editor version 9474; I have indicated what I think to be errors with <--

1.Language tour: assert((3 < 1) == 6); // 0011 << 1 == 0110
<-- in (3 < 1) must be <<

2.Style Guide:
DO use square brackets in doc comments for identifiers that are in scope.
If you surround things like variable, method or type names in square brackets, then documentation generators can look up the name and cross-link the two together.
/* Rolls both [Dice] and returns the highest rolled value. /
<-- / is not a doc comment!

3.Library Tour: Futures
Waiting for multiple futures
Future deleteDone = deleteLotsOfFiles();
Future copyDone = copyLotsOfFiles();
Future checksumDone = checksumLotsOfOtherFiles();

Futures.join([deleteDone, copyDone, checksumDone]).then(() {
print('Done with all the long steps');
});

<-- join gives a compiler warning:
'() -> ' is not assignable to '(List<>) -> void'
join method must be replaced with wait

4.Library Tour: Websockets
webSocket.on.message.add((e) {
receivedMessage(e.data);
});
<-- // warning: data is not a member of Event

5.Translations from Javascript: CheckNaN
Dart code should be:
var myNaN = 0/0;
if (myNaN.isNaN()) {
print('use isNaN to check if a number is NaN');
}
<-- So var myNaN instead of var myNan

6.Translations from Javascript: Value and Identity equality
var number5 = 5;
var char5 = '5';
number1 != char1
 last line should be: number5 != char5

7.Translations from Javascript: AJAX
// The getTEMPNAME method name will be changed.
var xhr = new XMLHttpRequest.getTEMPNAME("/data.json", (req) {
print("The contents of your data: ${req.responseText}");
});
<-- getTEMPNAME should be get

8.HTML Attributes:
element.attributes.contains('href') <-- contains should be containsKey

Thanks for this beautiful language and keep up the good work!
Cheers,
Ivo Balbaert

Original issue: http://code.google.com/p/dart/issues/detail?id=4117

[nicolasgarnier]

From [email protected] on July 18, 2012 08:05:12

Status: Triaged
Owner: [email protected]
Cc: [email protected]
Labels: Area-Site

[nicolasgarnier]

From [email protected] on August 16, 2012 15:50:02

Status: Accepted

[nicolasgarnier]

From [email protected] on August 17, 2012 11:16:18

Good feedback!

I'll take care of the tours (#1, 3, 4).

Bob, I can also take care of #2, if that's OK with you.

#8 (contains -> containsKey) seems to be reported against synonym but looks like it'll be an issue in other places (including the DOM and unit test articles). I'm guessing there was an API change in Map; the library tour is right, but the unit test article is wrong although it's almost as new. Once we have a way to test code snippets, we can catch stuff like this.

Seth, what's our plan for synonym? That's where the rest of the issues are.

Cc: [email protected] [email protected]

[nicolasgarnier]

From [email protected] on August 17, 2012 11:16:34

Labels: Milestone-M1

[nicolasgarnier]

From [email protected] on August 17, 2012 11:28:19

Bob, I can also take care of #2, if that's OK with you.

Thanks, that would rock!

[nicolasgarnier]

From [email protected] on September 11, 2012 17:01:04

Synonym updates are in scope for M1, thanks for the head's up!

[nicolasgarnier]

From [email protected] on September 11, 2012 17:54:30

#3 is fixed.
#4 is fixed.

I found one instance of incorrect contains (should have been containsKey). I don't think the unit test instance applies, as that's a matcher.

[nicolasgarnier]

From [email protected] on September 11, 2012 17:55:25

CL at https://chromiumcodereview.appspot.com/10910215/

[nicolasgarnier]

From [email protected] on September 12, 2012 18:28:09

Moved the synonym/translations bugs over to issue 5131

[nicolasgarnier]

From [email protected] on September 16, 2012 16:11:21

Hi Kathy,

Did these get address in the book?

[nicolasgarnier]

From [email protected] on September 17, 2012 14:52:57

Yes, the language/lib tour changes (1, 3, & 4) are fixed in the book. Also, I just pushed the fix to the style guide (2).

I think we're done, but let me know if we missed anything.

Status: Fixed