From 316d82a8d2e79b01158f336a79ac3767cd874883 Mon Sep 17 00:00:00 2001 From: Peli de Halleux Date: Tue, 7 Mar 2017 10:17:01 -0800 Subject: [PATCH] moving all js docs under "javascript" (#368) --- docs/javascript.md | 99 +++++++++++++++++---------- docs/{js => javascript}/call.md | 2 +- docs/{js => javascript}/classes.md | 0 docs/{js => javascript}/functions.md | 4 +- docs/{js => javascript}/inference.md | 0 docs/{js => javascript}/operators.md | 2 +- docs/{js => javascript}/sequence.md | 2 +- docs/{js => javascript}/statements.md | 2 +- docs/{js => javascript}/types.md | 2 +- docs/{js => javascript}/variables.md | 2 +- docs/js/faq.md | 58 ---------------- olddocs/js/bits.md | 4 +- olddocs/js/break.md | 6 +- olddocs/js/call.md | 8 +-- olddocs/js/code.md | 2 +- olddocs/js/comment.md | 8 +-- olddocs/js/for.md | 2 +- olddocs/js/function.md | 2 +- olddocs/js/functionparameters.md | 2 +- olddocs/js/if.md | 2 +- olddocs/js/image.md | 2 +- olddocs/js/libraries.md | 2 +- olddocs/js/math.md | 2 +- olddocs/js/number.md | 2 +- olddocs/js/operators.md | 2 +- olddocs/js/publishing.md | 2 +- olddocs/js/return.md | 2 +- olddocs/js/scriptid.md | 2 +- olddocs/js/statements.md | 2 +- olddocs/js/string-functions.md | 2 +- olddocs/js/string.md | 2 +- olddocs/js/while.md | 2 +- 32 files changed, 101 insertions(+), 132 deletions(-) rename docs/{js => javascript}/call.md (98%) rename docs/{js => javascript}/classes.md (100%) rename docs/{js => javascript}/functions.md (97%) rename docs/{js => javascript}/inference.md (100%) rename docs/{js => javascript}/operators.md (95%) rename docs/{js => javascript}/sequence.md (97%) rename docs/{js => javascript}/statements.md (97%) rename docs/{js => javascript}/types.md (99%) rename docs/{js => javascript}/variables.md (99%) delete mode 100644 docs/js/faq.md diff --git a/docs/javascript.md b/docs/javascript.md index 7bd81a92..f64c233e 100644 --- a/docs/javascript.md +++ b/docs/javascript.md @@ -1,42 +1,69 @@ # JavaScript -Visit the cards below to starting programming JavaScript -with the @boardname@: +We support a "static" subset of TypeScript +(itself a superset of JavaScript): -```codecard -[{ - "name": "Calling", - "url": "/js/call" -},{ - "name": "Sequencing", - "url": "/js/sequence" -},{ - "name": "Variables", - "url": "/js/variables" -},{ - "name": "Operators", - "url": "/js/operators" -},{ - "name": "Statements", - "url": "/js/statements" -},{ - "name": "Functions", - "url": "/js/functions" -},{ - "name": "Types", - "url": "/js/types" -},{ - "name": "Classes", - "url": "/js/classes" -},{ - "name": "FAQ", - "url": "/js/faq" -} -] -``` +* [Calling](/javascript/call) +* [Sequencing](/javascript/sequence) +* [Variables](/javascript/variables) +* [Operators](/javascript/operators) +* [Statements](/javascript/statements) +* [Functions](/javascript/functions) +* [Types](/javascript/types) +* [Classes](/javascript/classes) -### See Also -[calling](/js/call), [sequencing](/js/sequence), [variables](/js/variables), [operators](/js/operators), [statements](/js/statements), [functions](/js/functions), -[types](/js/types), [classes](/js/classes), [FAQ](/js/faq) \ No newline at end of file +## Supported language features + +* variables with `let` and `const` +* functions with lexical scoping and recursion +* top-level code in the file; hello world really is `console.log("Hello world")` +* `if ... else if ... else` statements +* `while` and `do ... while` loops +* `for(;;)` loops and for ... of +* `break/continue`; also with labeled loops +* `switch` statement (on numbers only) +* conditional operator `? :`; lazy boolean operators +* namespaces (a form of modules) +* all arithmetic operators (including bitwise operators); note that in microcontroller targets + all arithmetic is performed on integers, also when simulating in the browser +* strings (with a few common methods) +* [string templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) (`` `x is ${x}` ``) +* arrow functions `() => ...` +* classes with fields, methods and constructors; `new` keyword +* array literals [1, 2, 3] +* enums +* class inheritance + +## Unsupported language features + +We generally stay away from the more dynamic parts of JavaScript. +Things you may miss and we may implement: + +* exceptions (`throw`, `try ... catch`, `try ... finally`) +* `for ... in` statements +* object literals `{ foo: 1, bar: "two" }` +* method-like properties (get/set accessors) +* `debugger` statement for breakpoints + +For JS-only targets we may implement the following: + +* regular expressions +* classes implementing interfaces + +Things that we are not very likely to implement: + +* file-based modules (`import * from ...`, `module.exports` etc); we do support namespaces +* spread operator +* `yield` expression and ``function*`` +* `await` expression and `async function` +* `typeof` expression +* tagged templates ``tag `text ${expression} more text` ``; regular templates are supported +* binding with arrays or objects: `let [a, b] = ...; let { x, y } = ...` +* `with` statement +* `eval` +* `delete` statement +* `for ... in` statements +* JSX (HTML as part of JavaScript) + diff --git a/docs/js/call.md b/docs/javascript/call.md similarity index 98% rename from docs/js/call.md rename to docs/javascript/call.md index d93d23e8..711f459a 100644 --- a/docs/js/call.md +++ b/docs/javascript/call.md @@ -53,6 +53,6 @@ It's a syntax error to have a left parenthesis without the "closing" right paren basic.clearScreen( ``` -### ~button /js/sequence +### ~button /javascript/sequence NEXT: Sequencing Commands ### ~ diff --git a/docs/js/classes.md b/docs/javascript/classes.md similarity index 100% rename from docs/js/classes.md rename to docs/javascript/classes.md diff --git a/docs/js/functions.md b/docs/javascript/functions.md similarity index 97% rename from docs/js/functions.md rename to docs/javascript/functions.md index c36f4a0f..2823d05a 100644 --- a/docs/js/functions.md +++ b/docs/javascript/functions.md @@ -13,7 +13,7 @@ basic.showNumber(add(1, 2)) ``` ### ~ hint -For the @boardname@, you must specify a [type](/js/types) for each function parameter. +For the @boardname@, you must specify a [type](/javascript/types) for each function parameter. ### ~ Functions can refer to variables outside of the function body. @@ -167,6 +167,6 @@ function buildName(firstName: string, ...restOfName: string[]) { let buildNameFun: (fname: string, ...rest: string[]) => string = buildName; ``` -### ~button /js/types +### ~button /javascript/types NEXT: Types ### ~ \ No newline at end of file diff --git a/docs/js/inference.md b/docs/javascript/inference.md similarity index 100% rename from docs/js/inference.md rename to docs/javascript/inference.md diff --git a/docs/js/operators.md b/docs/javascript/operators.md similarity index 95% rename from docs/js/operators.md rename to docs/javascript/operators.md index 12354517..d2285785 100644 --- a/docs/js/operators.md +++ b/docs/javascript/operators.md @@ -18,6 +18,6 @@ This also is true when simulating in the browser. * comparison operators - [read more](http://devdocs.io/javascript/operators/comparison_operators) * conditional operator - [read more](http://devdocs.io/javascript/operators/conditional_operator) -### ~button /js/statements +### ~button /javascript/statements NEXT: Statements ### ~ \ No newline at end of file diff --git a/docs/js/sequence.md b/docs/javascript/sequence.md similarity index 97% rename from docs/js/sequence.md rename to docs/javascript/sequence.md index f26abb74..e58b2b8b 100644 --- a/docs/js/sequence.md +++ b/docs/javascript/sequence.md @@ -58,6 +58,6 @@ basic.showNumber(1); [Read more](http://inimino.org/~inimino/blog/javascript_semicolons) about semicolons in JavaScript. -### ~button /js/variables +### ~button /javascript/variables NEXT: Variable Declarations ### ~ \ No newline at end of file diff --git a/docs/js/statements.md b/docs/javascript/statements.md similarity index 97% rename from docs/js/statements.md rename to docs/javascript/statements.md index 92f77e94..330d8a91 100644 --- a/docs/js/statements.md +++ b/docs/javascript/statements.md @@ -27,6 +27,6 @@ The following JavaScript statements are supported for the @boardname@: * labelled statement - [read more](http://devdocs.io/javascript/statements/label) * `default` statement - [read more](http://devdocs.io/javascript/statements/default) -### ~button /js/functions +### ~button /javascript/functions NEXT: Functions ### ~ diff --git a/docs/js/types.md b/docs/javascript/types.md similarity index 99% rename from docs/js/types.md rename to docs/javascript/types.md index 91dca380..ae4754b6 100644 --- a/docs/js/types.md +++ b/docs/javascript/types.md @@ -136,6 +136,6 @@ function warnUser(): void { Declaring variables of type `void` is not useful. -### ~button /js/classes +### ~button /javascript/classes NEXT: Classes ### ~ \ No newline at end of file diff --git a/docs/js/variables.md b/docs/javascript/variables.md similarity index 99% rename from docs/js/variables.md rename to docs/javascript/variables.md index 9e96e40d..8ef39dea 100644 --- a/docs/js/variables.md +++ b/docs/javascript/variables.md @@ -128,6 +128,6 @@ const numLivesForCat = 9; They are like `let` declarations but, as their name implies, their value cannot be changed once they are bound. In other words, they have the same scoping rules as `let`, but you can't re-assign to them. -### ~button /js/operators +### ~button /javascript/operators NEXT: Operators ### ~ \ No newline at end of file diff --git a/docs/js/faq.md b/docs/js/faq.md deleted file mode 100644 index 905f2b8f..00000000 --- a/docs/js/faq.md +++ /dev/null @@ -1,58 +0,0 @@ -# Frequently asked questions - -# What is the language supported for the @boardname@? - -For the @boardname@, we support a "static" subset of TypeScript (itself a superset of JavaScript): - -## Supported language features - -* variables with `let` and `const` -* functions with lexical scoping and recursion -* top-level code in the file; hello world really is `console.log("Hello world")` -* `if ... else if ... else` statements -* `while` and `do ... while` loops -* `for(;;)` loops and for ... of -* `break/continue`; also with labeled loops -* `switch` statement (on numbers only) -* conditional operator `? :`; lazy boolean operators -* namespaces (a form of modules) -* all arithmetic operators (including bitwise operators); note that in microcontroller targets - all arithmetic is performed on integers, also when simulating in the browser -* strings (with a few common methods) -* [string templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) (`` `x is ${x}` ``) -* arrow functions `() => ...` -* classes with fields, methods and constructors; `new` keyword -* array literals `[1, 2, 3]` -* enums -* class inheritance - -## Unsupported language features - -We generally stay away from the more dynamic parts of JavaScript. -Things you may miss and we may implement: - -* exceptions (`throw`, `try ... catch`, `try ... finally`) -* `for ... in` statements -* object literals `{ foo: 1, bar: "two" }` -* method-like properties (get/set accessors) -* `debugger` statement for breakpoints - -For JS-only targets we may implement the following: - -* regular expressions -* classes implementing interfaces - -Things that we are not very likely to implement: - -* file-based modules (`import * from ...`, `module.exports` etc); we do support namespaces -* spread operator -* `yield` expression and ``function*`` -* `await` expression and `async function` -* `typeof` expression -* tagged templates ``tag `text ${expression} more text` ``; regular templates are supported -* binding with arrays or objects: `let [a, b] = ...; let { x, y } = ...` -* `with` statement -* `eval` -* `delete` statement -* `for ... in` statements -* JSX (HTML as part of JavaScript) diff --git a/olddocs/js/bits.md b/olddocs/js/bits.md index 0789cbcc..693ac82b 100644 --- a/olddocs/js/bits.md +++ b/olddocs/js/bits.md @@ -6,7 +6,7 @@ Functions in the Bits library. The binary numeral system represents numeric values using values 0 and 1. This is how almost all modern computers store data. Each 0 or 1 digit is called a binary digit, or bit for short. -The Bits library includes functions for bit-level manipulation of integers. In the [Touch Develop editor](/js/editor), click `bits` to see the following bit functions: +The Bits library includes functions for bit-level manipulation of integers. In the [Touch Develop editor](/javascript/editor), click `bits` to see the following bit functions: ## Bitwise and, or, and xor functions @@ -63,5 +63,5 @@ bits `->` shift right unint32 (x : [Number](/reference/types/number), bits : [Nu ### See also -[statements and operators](/js/statements), [math functions](/js/math), [Number](/reference/types/number) +[statements and operators](/javascript/statements), [math functions](/javascript/math), [Number](/reference/types/number) diff --git a/olddocs/js/break.md b/olddocs/js/break.md index e318720f..11e0dd10 100644 --- a/olddocs/js/break.md +++ b/olddocs/js/break.md @@ -2,10 +2,10 @@ Break statement; exit a for or while loop. -### @parent js/language +### @parent javascript/language -Exit a [while](/js/while) or [for](/reference/loops/for) loop before the loop is complete. +Exit a [while](/javascript/while) or [for](/reference/loops/for) loop before the loop is complete. ### Touch Develop syntax @@ -29,5 +29,5 @@ for (let i = 0; i < 10; i++) { ### See also -[for](/reference/loops/for), [while](/js/while) +[for](/reference/loops/for), [while](/javascript/while) diff --git a/olddocs/js/call.md b/olddocs/js/call.md index 42822e1f..20a4a603 100644 --- a/olddocs/js/call.md +++ b/olddocs/js/call.md @@ -2,14 +2,14 @@ How to call a function in your code. -### @parent js/language +### @parent javascript/language -Type a function name in your code to call an existing [function](/js/function) in your script. +Type a function name in your code to call an existing [function](/javascript/function) in your script. ### Call a function -1. In the Touch Develop editor, click a line of code to open the on-screen [Code Keyboard](/js/editor). +1. In the Touch Develop editor, click a line of code to open the on-screen [Code Keyboard](/javascript/editor). 2. Click `code` to see the functions in your script. @@ -59,5 +59,5 @@ To see a list of the functions in a script, open the script and then click `scri ### See also -[function parameters](/js/functionparameters), [create a function](/js/function), [return statement](/js/return) +[function parameters](/javascript/functionparameters), [create a function](/javascript/function), [return statement](/javascript/return) diff --git a/olddocs/js/code.md b/olddocs/js/code.md index ea35a75a..060babfc 100644 --- a/olddocs/js/code.md +++ b/olddocs/js/code.md @@ -2,7 +2,7 @@ A function with inputs and outputs. -### @parent js/language +### @parent javascript/language To add a **functions** to your script, click the `script` button, then click the `+` `add new function` button diff --git a/olddocs/js/comment.md b/olddocs/js/comment.md index 19f1afe3..60bba33e 100644 --- a/olddocs/js/comment.md +++ b/olddocs/js/comment.md @@ -2,7 +2,7 @@ A note in code. -### @parent js/statement +### @parent javascript/statement A comment is a line of code that contains text, usually an explanation or a note. All comments are ignored during script execution. @@ -59,10 +59,10 @@ When you want to uncomment your code, click the `if false then` statement in you ### Library and function comments -* Use [comments](/js/comment) at the beginning of a library to describe the library -* Use [comments](/js/comment) at the beginning of a [function](/js/function) to describe a function. The comment will appear in the help area of the Touch Develop editor when you insert the function +* Use [comments](/javascript/comment) at the beginning of a library to describe the library +* Use [comments](/javascript/comment) at the beginning of a [function](/javascript/function) to describe a function. The comment will appear in the help area of the Touch Develop editor when you insert the function ### See also -[markdown syntax](/js/markdown), [Touch Develop editor](/js/editor) +[markdown syntax](/javascript/markdown), [Touch Develop editor](/javascript/editor) diff --git a/olddocs/js/for.md b/olddocs/js/for.md index f219c572..174fec81 100644 --- a/olddocs/js/for.md +++ b/olddocs/js/for.md @@ -2,7 +2,7 @@ Repeat code a preset number of times. -### @parent js/language +### @parent javascript/language Repeat code a fixed number of times. diff --git a/olddocs/js/function.md b/olddocs/js/function.md index c9b052d9..ea22740b 100644 --- a/olddocs/js/function.md +++ b/olddocs/js/function.md @@ -2,7 +2,7 @@ How to define a function with input and output parameters. -### @parent js/language +### @parent javascript/language A function is a unit of code that performs a specific task and returns a result. diff --git a/olddocs/js/functionparameters.md b/olddocs/js/functionparameters.md index 26ae4272..20ea12bd 100644 --- a/olddocs/js/functionparameters.md +++ b/olddocs/js/functionparameters.md @@ -2,7 +2,7 @@ How to use parameters to pass info in and out of an function. -### @parent js/function +### @parent javascript/function A [function](/js/function) can have multiple input parameters and/or a single output parameter. The parameters must be one of the supported variable [types](/js/types). diff --git a/olddocs/js/if.md b/olddocs/js/if.md index 2411694d..218695ba 100644 --- a/olddocs/js/if.md +++ b/olddocs/js/if.md @@ -2,7 +2,7 @@ Run code based on a condition. -### @parent js/language +### @parent javascript/language Conditionally run code depending on whether a [Boolean](/reference/types/boolean) condition is true or false. diff --git a/olddocs/js/image.md b/olddocs/js/image.md index 4d877104..d823d184 100644 --- a/olddocs/js/image.md +++ b/olddocs/js/image.md @@ -2,7 +2,7 @@ An image for the @boardname@ screen. -### @parent js/language +### @parent javascript/language An *Image* is a matrix of pixels to show on the [LED screen](/device/screen) diff --git a/olddocs/js/libraries.md b/olddocs/js/libraries.md index 2e402224..8f0be3e0 100644 --- a/olddocs/js/libraries.md +++ b/olddocs/js/libraries.md @@ -2,7 +2,7 @@ Libraries are scripts with functions that you can use in other scripts. -### @parent js/language +### @parent javascript/language Libraries are scripts with functions that you can use in other scripts. For example, `game` is a library of game-related functions that you can use in your scripts. diff --git a/olddocs/js/math.md b/olddocs/js/math.md index 955e856a..4a28fe44 100644 --- a/olddocs/js/math.md +++ b/olddocs/js/math.md @@ -2,7 +2,7 @@ Functions in the math library. -### @parent js/language +### @parent javascript/language The math library includes math related functions that you can use with [Numbers](/reference/types/number). diff --git a/olddocs/js/number.md b/olddocs/js/number.md index 7b81dc68..4f057a86 100644 --- a/olddocs/js/number.md +++ b/olddocs/js/number.md @@ -2,7 +2,7 @@ An integer number. -### @parent js/language +### @parent javascript/language A *Number* is an integer such as `42` or `-42`. More precisely, a *Number* is a signed 32-bit integer (two's complement). diff --git a/olddocs/js/operators.md b/olddocs/js/operators.md index 51ee5ce2..e466b51c 100644 --- a/olddocs/js/operators.md +++ b/olddocs/js/operators.md @@ -2,7 +2,7 @@ Built-in operators. -### @parent js/language +### @parent javascript/language ### to be removed: has been combined into [statements and operators](/js/statements) diff --git a/olddocs/js/publishing.md b/olddocs/js/publishing.md index 05069fdd..faf7851d 100644 --- a/olddocs/js/publishing.md +++ b/olddocs/js/publishing.md @@ -2,7 +2,7 @@ How to publish scripts. -### @parent js/contents +### @parent javascript/contents Scripts that you create are periodically saved in the cloud, but only published scripts can be seen by other people. Once you publish a script, other people can run your script, post comments on it, tweak and re-publish it, or rate your script with a heart. diff --git a/olddocs/js/return.md b/olddocs/js/return.md index 57f45c22..a0bf5740 100644 --- a/olddocs/js/return.md +++ b/olddocs/js/return.md @@ -2,7 +2,7 @@ Exit a function. -### @parent js/statement +### @parent javascript/statement The return statement exits a [function](/js/function) and returns a value to the code that called the function. diff --git a/olddocs/js/scriptid.md b/olddocs/js/scriptid.md index fdbe476d..2b8a5201 100644 --- a/olddocs/js/scriptid.md +++ b/olddocs/js/scriptid.md @@ -2,7 +2,7 @@ What is the script id? #docs -### @parent js/contents +### @parent javascript/contents the *script id* is a unique identifier that is given to each [published](/js/publishing) script. This way you can share your scripts with other people. diff --git a/olddocs/js/statements.md b/olddocs/js/statements.md index 0c7019c5..79210ff5 100644 --- a/olddocs/js/statements.md +++ b/olddocs/js/statements.md @@ -2,7 +2,7 @@ Statements, operators, and libraries. -### @parent js/language +### @parent javascript/language TouchDevelop functions include statements and operators. diff --git a/olddocs/js/string-functions.md b/olddocs/js/string-functions.md index 73ba8f39..333a25a8 100644 --- a/olddocs/js/string-functions.md +++ b/olddocs/js/string-functions.md @@ -2,7 +2,7 @@ string-related functions. -### @parent js/language +### @parent javascript/language The following string related functions are available in Touch Develop for the @boardname@: diff --git a/olddocs/js/string.md b/olddocs/js/string.md index 109c077a..9f2b225b 100644 --- a/olddocs/js/string.md +++ b/olddocs/js/string.md @@ -2,7 +2,7 @@ a piece of text. -### @parent js/language +### @parent javascript/language A *String* is a sequence of characters. For the @boardname@, ASCII character codes 32 to 126 are supported; letters, digits, punctuation marks, and a few symbols. All other character codes appear as a ? on the [LED screen](/device/screen). diff --git a/olddocs/js/while.md b/olddocs/js/while.md index c50dd1b3..2f44d9e4 100644 --- a/olddocs/js/while.md +++ b/olddocs/js/while.md @@ -2,7 +2,7 @@ Repeat code in a loop while a condition is true. -### @parent js/language +### @parent javascript/language Repeat code while a [Boolean](/reference/types/boolean) `condition` is true.