Update documentation for 1.3.x #528

gzm0 · 2020-12-08T13:03:12Z

As a side effect, update the Node.js ES module support section.

sjrd

Thanks for tackling this :)

sjrd · 2020-12-08T13:42:13Z

doc/project/building.md


-By default, Scala.js produces "libraries", that do not actually *do* anything when their `-fastopt.js` file is loaded.
-To make it do something, you need a top-level object with a `main` method:
+To produce JavaScript, we need to either expose something (e.g. a method or a class) or do something when the JavaScript is loaded.


Suggested change

To produce JavaScript, we need to either expose something (e.g. a method or a class) or do something when the JavaScript is loaded.

To produce JavaScript code, we need to either export something (e.g. a method or a class) or do something when the JavaScript code is loaded.

? "produce JavaScript" sounds odd to me. It's like producing the JavaScript language as a whole; not producing some JavaScript code.

sjrd · 2020-12-08T13:45:12Z

doc/project/building.md

+To produce JavaScript, we need to either expose something (e.g. a method or a class) or do something when the JavaScript is loaded.
+Otherwise, Scala.js will not produce any JavaScript code (because to do nothing, there is no need for any code).
+
+To do something when your code is loaded, you need a top-level object with a `main` method (to expose something, see [Export Scala.js APIs to JavaScript]({{ site.production_url }}/doc/interoperability/export-to-javascript.html)).


Suggested change

To do something when your code is loaded, you need a top-level object with a `main` method (to expose something, see [Export Scala.js APIs to JavaScript]({{ site.production_url }}/doc/interoperability/export-to-javascript.html)).

To do something when your code is loaded, you need a top-level object with a `main` method (to export something, see [Export Scala.js APIs to JavaScript]({{ site.production_url }}/doc/interoperability/export-to-javascript.html)).

sjrd · 2020-12-08T13:46:03Z

doc/project/building.md

 `js.JSApp` is now deprecated.
 See [the Scaladoc of `js.JSApp`]({{ site.production_url }}/api/scalajs-library/0.6.20/#scala.scalajs.js.JSApp) for migration tips.

+## Produce JavaScript


Suggested change

## Produce JavaScript

## Produce JavaScript code

and several more times below.

Also above, in the no-diff area, there is still:

Now, the .js file produced by fastOptJS will print "Hello world!".

which should not only be replaced by fastLinkJS, but also probably reworked, because now at that point we haven't tried to do anything yet.

sjrd · 2020-12-08T13:48:44Z

doc/project/building.md

+
+ sbt> fastLinkJS
+
+This will perform fast Scala.js-specific optimizations and write the resulting code to a directory. With the default options, it will write a single file `main.js`. You can now use this JavaScript file in your HTML page or in whatever way you like. The resulting directory in the target folder will have the suffix `-fastopt`.


Consider using one line per sentence for new paragraphs. IMO it yields better diffs on subsequent edits:

Suggested change

This will perform fast Scala.js-specific optimizations and write the resulting code to a directory. With the default options, it will write a single file `main.js`. You can now use this JavaScript file in your HTML page or in whatever way you like. The resulting directory in the target folder will have the suffix `-fastopt`.

This will perform fast Scala.js-specific optimizations and write the resulting code to a directory.

With the default options, it will write a single file `main.js`.

You can now use this JavaScript file in your HTML page or in whatever way you like.

The resulting directory in the target folder will have the suffix `-fastopt`.

sjrd · 2020-12-08T13:51:37Z

doc/project/building.md

+
+This will perform fast Scala.js-specific optimizations and write the resulting code to a directory. With the default options, it will write a single file `main.js`. You can now use this JavaScript file in your HTML page or in whatever way you like. The resulting directory in the target folder will have the suffix `-fastopt`.
+
+**Note for Scala.js 1.2.x and earlier:** in Scala.js 1.2.x and earlier, `fastLinkJS` was called `fastOptJS` and always produced a single file with the suffix `-fastopt.js` directly in the target directory.


fastLinkJS was called fastOptJS

That's a bit misleading. We haven't renamed fastOptJS. It is even still there. Perhaps phrase this as follows:

Suggested change

**Note for Scala.js 1.2.x and earlier:** in Scala.js 1.2.x and earlier, `fastLinkJS` was called `fastOptJS` and always produced a single file with the suffix `-fastopt.js` directly in the target directory.

**Note for Scala.js 1.2.x and earlier:** in Scala.js 1.2.x and earlier, we used `fastOptJS` instead of `fastLinkJS`, which always produces a single file with the suffix `-fastopt.js` directly in the target directory.

sjrd · 2020-12-08T13:52:51Z

doc/project/building.md


 sbt> set scalaJSStage in Global := FullOptStage

+**Note for Scala.js 1.2.x and earlier:** in Scala.js 1.2.x and earlier, `fullLinkJS` was called `fullOptJS` and always produced a single file with the suffix `-opt.js`. `scalaJSStage` works the same way in Scala.js 1.2.x and in later versions.


Same remark.

sjrd · 2020-12-08T13:53:16Z

doc/project/linking-errors.md

 ---

-When linking a Scala.js application, either directly through `fastOptJS`/`fullOptJS` or indirectly through `run` or `test`, Scala.js can sometimes report *linking errors*.
+When linking a Scala.js application, either directly through `fastLinkJS` / `fullLinkJS` (`fastOptJS`/`fullOptJS` up to Scala.js 1.2.x) or indirectly through `run` or `test`, Scala.js can sometimes report *linking errors*.


Suggested change

When linking a Scala.js application, either directly through `fastLinkJS` / `fullLinkJS` (`fastOptJS`/`fullOptJS` up to Scala.js 1.2.x) or indirectly through `run` or `test`, Scala.js can sometimes report *linking errors*.

When linking a Scala.js application, either directly through `fastLinkJS`/`fullLinkJS` (`fastOptJS`/`fullOptJS` up to Scala.js 1.2.x) or indirectly through `run` or `test`, Scala.js can sometimes report *linking errors*.

sjrd · 2020-12-08T13:56:36Z

doc/project/module.md


-Support for ECMAScript modules is [still experimental in Node.js](https://nodejs.org/api/esm.html).
-To run and test a Scala.js application or library using ES modules with Node.js, you will need the following additional settings:
+Node.js needs explicit signalling that a module is an ECMAScript module (the default is CommonJS).


We typically use American spelling:

Suggested change

Node.js needs explicit signalling that a module is an ECMAScript module (the default is CommonJS).

Node.js needs explicit signaling that a module is an ECMAScript module (the default is CommonJS).

sjrd · 2020-12-08T13:57:33Z

doc/project/module.md

+- Use the file extension `.mjs`.
+- Configure it in `package.json`.


We typically use * for bulleted lists. (- in Scaladocs because that's the only thing it understands)

Suggested change

- Use the file extension `.mjs`.

- Configure it in `package.json`.

* Use the file extension `.mjs`.

* Configure it in `package.json`.

sjrd · 2020-12-08T13:59:01Z

doc/project/testing.md

+## Testing over `fullLinkJS`-generated files

-By default, tests runs over `fastOptJS`-built JS files since their build time are shorter than `fullOptJS`.
+By default, tests runs over `fastLinkJS`-built (`fastOptJS` up to Scala.js 1.2.x) JS files since their build time are shorter than `fullLinkJS` (`fullLinkJS` up to Scala.js 1.2.x).


Suggested change

By default, tests runs over `fastLinkJS`-built (`fastOptJS` up to Scala.js 1.2.x) JS files since their build time are shorter than `fullLinkJS` (`fullLinkJS` up to Scala.js 1.2.x).

By default, tests run over `fastLinkJS`-built (resp. `fastOptJS` up to Scala.js 1.2.x) JS files since their build time is shorter than `fullLinkJS` (resp. `fullLinkJS`).

As a side effect, update the Node.js ES module support section.

gzm0 · 2020-12-08T16:20:37Z

Updated. I hope I have addressed everything.

gzm0 requested a review from sjrd December 8, 2020 13:03

sjrd requested changes Dec 8, 2020

View reviewed changes

Update documentation for 1.3.x

1748597

As a side effect, update the Node.js ES module support section.

gzm0 force-pushed the update-fastlink branch from 2000115 to 1748597 Compare December 8, 2020 16:20

sjrd approved these changes Dec 8, 2020

View reviewed changes

gzm0 merged commit 9799280 into scala-js:master Dec 9, 2020

gzm0 deleted the update-fastlink branch December 9, 2020 08:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update documentation for 1.3.x #528

Update documentation for 1.3.x #528

Uh oh!

gzm0 commented Dec 8, 2020

sjrd left a comment

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

sjrd Dec 8, 2020

gzm0 commented Dec 8, 2020

Labels

2 participants

	To produce JavaScript, we need to either expose something (e.g. a method or a class) or do something when the JavaScript is loaded.
	To produce JavaScript code, we need to either export something (e.g. a method or a class) or do something when the JavaScript code is loaded.

	To do something when your code is loaded, you need a top-level object with a `main` method (to expose something, see [Export Scala.js APIs to JavaScript]({{ site.production_url }}/doc/interoperability/export-to-javascript.html)).
	To do something when your code is loaded, you need a top-level object with a `main` method (to export something, see [Export Scala.js APIs to JavaScript]({{ site.production_url }}/doc/interoperability/export-to-javascript.html)).


		sbt> fastLinkJS

		This will perform fast Scala.js-specific optimizations and write the resulting code to a directory. With the default options, it will write a single file `main.js`. You can now use this JavaScript file in your HTML page or in whatever way you like. The resulting directory in the target folder will have the suffix `-fastopt`.


		This will perform fast Scala.js-specific optimizations and write the resulting code to a directory. With the default options, it will write a single file `main.js`. You can now use this JavaScript file in your HTML page or in whatever way you like. The resulting directory in the target folder will have the suffix `-fastopt`.

		Note for Scala.js 1.2.x and earlier: in Scala.js 1.2.x and earlier, `fastLinkJS` was called `fastOptJS` and always produced a single file with the suffix `-fastopt.js` directly in the target directory.


		sbt> set scalaJSStage in Global := FullOptStage

		Note for Scala.js 1.2.x and earlier: in Scala.js 1.2.x and earlier, `fullLinkJS` was called `fullOptJS` and always produced a single file with the suffix `-opt.js`. `scalaJSStage` works the same way in Scala.js 1.2.x and in later versions.

	When linking a Scala.js application, either directly through `fastLinkJS` / `fullLinkJS` (`fastOptJS`/`fullOptJS` up to Scala.js 1.2.x) or indirectly through `run` or `test`, Scala.js can sometimes report linking errors.
	When linking a Scala.js application, either directly through `fastLinkJS`/`fullLinkJS` (`fastOptJS`/`fullOptJS` up to Scala.js 1.2.x) or indirectly through `run` or `test`, Scala.js can sometimes report linking errors.

	Node.js needs explicit signalling that a module is an ECMAScript module (the default is CommonJS).
	Node.js needs explicit signaling that a module is an ECMAScript module (the default is CommonJS).

		- Use the file extension `.mjs`.
		- Configure it in `package.json`.

	By default, tests runs over `fastLinkJS`-built (`fastOptJS` up to Scala.js 1.2.x) JS files since their build time are shorter than `fullLinkJS` (`fullLinkJS` up to Scala.js 1.2.x).
	By default, tests run over `fastLinkJS`-built (resp. `fastOptJS` up to Scala.js 1.2.x) JS files since their build time is shorter than `fullLinkJS` (resp. `fullLinkJS`).

Update documentation for 1.3.x #528

Update documentation for 1.3.x #528

Uh oh!

Conversation

gzm0 commented Dec 8, 2020

sjrd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gzm0 commented Dec 8, 2020

Labels

2 participants