search

emojicode / emojicode.github.io

The Emojicode Documentation
http://www.emojicode.org
81 stars 42 forks source link

Control Flow Documentation Issues #78

Open flwyd opened 3 years ago

flwyd commented 3 years ago
  1. The code example for the 🔁 For-in loop is incorrect. It starts a list declaration with 🍨 rather than 🍿.
  2. The explanation of 🔁 For-In compiled bytecode is a bit confusing because it appears before 🔁 Repeat-While is introduced.
  3. The 🙅↪️ Else-If section is confusing. The sentence "However, unlike ↪️, it will execute that alternative expressions only if the ↪️ expression is 👍" doesn't make much sense: both ↪️ and 🙅↪️ execute a block if the associated expression is 👍. (Additionally, "that" and "expressions" disagree in grammatical case; it should either be "that alternative expression" singular or "those alternative expressions" plural, though maybe it should actually be talking about an "alternative block"?) Perhaps this should be reworded to say that 🙅↪️ evaluates its expression if no previous 🙅↪️ or ↪️ in the sequence evaluated to 👍.
  4. The Markdown-generated header tags have an id attribute based on the section title. Emoji in that title are replaced with -. This results in multiple HTML elements with the same id when a section header doesn't have any ASCII text. This makes fragment links to that section impossible. For example, <h3 id="-">🙅</h3> and <h3 id="-">🙅↪️</h3> conflict for the fragment in https://www.emojicode.org/docs/reference/controlflow.html#-
  5. The comments in the code example for ⏩ ranges don't properly explain the use of step. The first comment says "Prints numbers 0 through 8 (including)" but it actually only prints the even numbers (0 2 4 6 8). The 100 -10 -10 example might be more illustrative if it were 100 -15 10 which would (a) help convey that the second argument is the end and the third is the step and (b) illustrate the surprising behavior when abs(end - start) is not a multiple of step (the range seems to go from start to end - step inclusive, rather than from start to end exclusive).

(Code observations based on Emojicode-1.0-beta.2-Darwin-x86_64.)

thbwd commented 3 years ago

Thanks for so carefully reading the documentation and bringing up all these suggestions! I'll look at the rest of these later. Always feel free to up a pull request! In some cases it may be easier to just change it instead of writing an explanation.