DOC: Comments on Source §1 documentation

[chrisjwelly]

Some comments regarding Source §1 documentation:

1. For the section on function definition expression, we should avoid using the map as an example. I imagine that students will visit this Source §1 documentation in either the first or second week of the semester. They would not have learnt the list libraries and can be left confused by the example. May I suggest the example to be a simple:

(x => x * x)(3); // returns 9

I think this still illustrates the fact that function definition expressions don't require a name.

2. For the section on undefined. The textbook is referenced with "See also textbook explanation in chapter 4."
   While this is not wrong as by the URL, the explanation is located in "chapter 4", I think we should call it "Section 1.1.2". This can avoid the confusion of interpreting "chapter 4" as in "Source §4"
3. Throughout the documentation of math libraries function, points about "+0" and "-0" are almost always raised. In Source (or Source Academy at least), is there a distinction between these two? In the Source Academy REPL, both +0 and -0 return 0. This can also potentially confuse students.
4. For math_max, math_min and stringify, the names are written with math_max(), math_min(), and stringify() respectively. This may suggest to readers that these are functions with no parameters. I'm not really sure how to best document this either. I think ... is a possibility which we can add?
5. Two versions of parse_int are documented: parse_int(str, radix), and parse_int(s, i). Reading through the descriptions, I feel that the two of them are the same. Is there a distinction between the two?
6. Minor: A typo in the MATH page. "An implmentation of Source does not need to check whether ...."
7. Nice-to-have: When going from Source 1 main documentation to a predeclared names documentation, I can only go back to the main documentation by pressing the back button on my browser. If a user is linked directly to the predeclared names, the user has no option to go to the main documentation. May I suggest that "Source §1" in the heading of predeclared names documentation link back to the main documentation?

[martin-henz]

Some comments regarding Source §1 documentation:

1. For the section on function definition expression, we should avoid using the map as an example. I imagine that students will visit this Source §1 documentation in either the first or second week of the semester. They would not have learnt the list libraries and can be left confused by the example. May I suggest the example to be a simple:

(x => x * x)(3); // returns 9

I think this still illustrates the fact that function definition expressions don't require a name.

Fixed in #271

1. For the section on undefined. The textbook is referenced with "See also textbook explanation in chapter 4."

   While this is not wrong as by the URL, the explanation is located in "chapter 4", I think we should call it "Section 1.1.2". This can avoid the confusion of interpreting "chapter 4" as in "Source §4"

Fixed in #271

2. Throughout the documentation of math libraries function, points about "+0" and "-0" are almost always raised. In Source (or Source Academy at least), is there a distinction between these two? In the Source Academy REPL, both +0 and -0 return 0. This can also potentially confuse students.

Yes, this is a quirk of IEEE754: +0 and -0 are different.

A (somewhat weird) example:

math_atanh(-1, 1/0) === 0; // returns false although
math_atanh(-1, 1/0); // returns 0

The actual result of math_atanh(-1, 1/0) is -0, which according to IEEE754 is different from +0.

The lesson from this, I think: We shouldn't just copy the JavaScript specs. Instead we should simplify and remove all these weird cases. Instead, we should refer to the JavaScript specs for details.

Done in #271

3. For math_max, math_min and stringify, the names are written with math_max(), math_min(), and stringify() respectively. This may suggest to readers that these are functions with no parameters. I'm not really sure how to best document this either. I think ... is a possibility which we can add?

stringify: fixed
math_max and min: havent figured out how to put ... in the doc using jsdoc
ignoring this minor issue

4. Two versions of parse_int are documented: parse_int(str, radix), and parse_int(s, i). Reading through the descriptions, I feel that the two of them are the same. Is there a distinction between the two?

Removed the inferior version

5. Minor: A typo in the MATH page. "An implmentation of Source does not need to check whether ...."

fixed

6. Nice-to-have: When going from Source 1 main documentation to a predeclared names documentation, I can only go back to the main documentation by pressing the back button on my browser. If a user is linked directly to the predeclared names, the user has no option to go to the main documentation. May I suggest that "Source §1" in the heading of predeclared names documentation link back to the main documentation?

Fixed in #271