feat(SDK): add JSDoc comments

docs/docs/configuration/configuration-object.md

@@ -125,19 +125,19 @@ Default: `{ language: "html", content: "" }`
 An object that configures the language and content of the markup editor. This can include the following properties:
 
 - `language`:  
-  Type: [Language](../api/modules/internal.md#language)  
+  Type: [Language](../api/modules#language)  
   Default: `"html"` in markup editor, `"css"` in style editor and `"javascript"` in script editor.  
   This can be a language name, extension or alias (as defined in [language documentations](../languages/index.md)).  
   (e.g. `"markdown"`, `"md"`)
 
 - `title`:
   Type: [`string | undefined`](../api/interfaces/internal.Editor#title)  
-  Default: `""`
+  Default: `""`  
   If set, this is used as the title of the editor in the UI, overriding the default title set to the language name (e.g. "Python" can be used instead of "Py (Wasm)").
 
 - `content`:
   Type: [`string | undefined`](../api/interfaces/internal.Editor#content)  
-  Default: `""`
+  Default: `""`  
   The initial content of the code editor.
 
 - `contentUrl`:
@@ -166,7 +166,8 @@ An object that configures the language and content of the markup editor. This ca
 - `position`:
   Type: [`{lineNumber: number, column?: number} | undefined`](../api/interfaces/internal.Editor#position)  
   Default: `undefined`  
-  The initial position of the cursor in the code editor.
+  The initial position of the cursor in the code editor.  
+  Example: `{lineNumber: 5, column: 10}`
 
 ### `style`
 
@@ -210,7 +211,7 @@ Default: `""`
 
 ### `processors`
 
-Type: [`Processor[]`](../api/modules#processor)
+Type: [`Processor[]`](../api/modules/internal/#processor)
 
 Default: `[]`
 
@@ -245,8 +246,8 @@ would add this import map in the result page:
 <script type="importmap">
   {
     "imports": {
-      "moment": "https://cdn.skypack.dev/moment",
-      "lodash": "https://cdn.skypack.dev/lodash"
+      "moment": "https://esm.sh/moment",
+      "lodash": "https://esm.sh/lodash"
     }
   }
 </script>
@@ -269,7 +270,7 @@ The import map becomes like this:
   {
     "imports": {
       "moment": "https://cdn.jsdelivr.net/npm/moment@2.29.4/dist/moment.js",
-      "lodash": "https://cdn.skypack.dev/lodash"
+      "lodash": "https://esm.sh/lodash"
     }
   }
 </script>
@@ -384,7 +385,7 @@ Type: [`"full" | "focus" | "simple" | "result" | "editor" | "codeblock"`](../api
 
 Default: `"full"`
 
-Sets [display mode](../features/display-modes.md)
+Sets the [display mode](../features/display-modes.md).
 
 ### `tools`
 
@@ -458,7 +459,7 @@ Type: [`number`](../api/interfaces/Config.md#delay)
 
 Default: `1500`
 
-Time delay (in milliseconds) follwing code change, after which the result page is updated (if [`autoupdate`](#autoupdate) is `true`) and/or the project is saved (if [`autosave`](#autosave) is `true`).
+Time delay (in milliseconds) following code change, after which the result page is updated (if [`autoupdate`](#autoupdate) is `true`) and/or the project is saved (if [`autosave`](#autosave) is `true`).
 
 ### `formatOnsave`
 
@@ -490,7 +491,7 @@ Type: [`EditorTheme[] | string | undefined`](../api/interfaces/Config.md#editort
 
 Default: `undefined`
 
-Sets the editor [themes](../features/themes.md).
+Sets the code editor themes.
 
 :::info Note
 You can preview and set editor themes in the [editor settings screen](pathname:///../?screen=editor-settings).
@@ -540,7 +541,7 @@ Type: [`boolean`](../api/interfaces/Config.md#welcome)
 
 Default: `true`
 
-Shows the [welcome screen](../features/welcome.md) when the app loads.
+If `true`, the [welcome screen](../features/welcome.md) is displayed when the app loads.
 
 ### `showSpacing`
 
@@ -624,7 +625,7 @@ Type: [`boolean`](../api/interfaces/Config.md#emmet)
 
 Default: `true`
 
-Enables [emmet](../features/editor-settings.md#emmet).
+Enables [Emmet](../features/editor-settings.md#emmet).
 
 ### `editorMode`
 

docs/docs/sdk/index.md

@@ -8,7 +8,7 @@ import LiveCodes from '../../src/components/LiveCodes.tsx'
 
 The Software Development Kit (SDK) provides an easy, yet powerful, interface to embed and communicate with LiveCodes playgrounds.
 
-The SDK is provided as a light-weight, zero-dependencies [npm package](#npm-package), that is also available from [CDNs](#cdn). It can be used to create playgrounds with a wide variety of [configurations](../configuration/configuration-object.md) and [embed options](js-ts.md#embed-options). In addition, [SDK methods](js-ts.md#sdk-methods) allow programmatic communication and control of the playgrounds during runtime.
+The SDK is provided as a light-weight ([less than 5kb gzipped](https://bundlephobia.com/package/livecodes)), zero-dependencies [npm package](#npm-package), that is also available from [CDNs](#cdn). It can be used to create playgrounds with a wide variety of [configurations](../configuration/configuration-object.md) and [embed options](js-ts.md#embed-options). In addition, [SDK methods](js-ts.md#sdk-methods) allow programmatic communication and control of the playgrounds during runtime.
 
 The [JavaScript SDK](js-ts.md) is framework/library agnostic. However, wrapper components are also provided for popular libraries (currently [React](react.md) and [Vue](vue.md)). The SDK can be used in [Svelte](svelte.md) directly without wrappers. [TypeScript support](js-ts.md#typescript-types) provides type-safety and a great developer experience.
 

docs/docs/sdk/js-ts.md

@@ -7,7 +7,7 @@ title: JS/TS SDK
 import LiveCodes from '../../src/components/LiveCodes.tsx'
 import RunInLiveCodes from '../../src/components/RunInLiveCodes.tsx'
 
-This is the core SDK on which others ([React](react.md), [Vue](vue.md), and [Svelte](svelte.md) SDKs) are build on top. It is a lightweight library (less than 5kb gzipped) that allows creating, embedding and communication with LiveCodes playgrounds. It also allows easily creating links to playgrounds.
+This is the core SDK on which others ([React](react.md), [Vue](vue.md), and [Svelte](svelte.md) SDKs) are build on top. It is a light-weight ([less than 5kb gzipped](https://bundlephobia.com/package/livecodes)), zero-dependencies library that allows creating, embedding and communication with LiveCodes playgrounds. It also allows easily creating links to playgrounds.
 
 ## Installation
 
@@ -35,7 +35,7 @@ Type: [`(container: string | Element, options?: EmbedOptions) => Promise<Playgro
 
 The library exports the function `createPlayground` which has 2 parameters:
 
-- `container` (required): `HTMLElement` or a string representing a CSS selector.  
+- `container` (required): `HTMLElement` or a string representing a CSS selector. This is the container where the playground is rendered.
   If not found, an error is thrown (except in [headless mode](./headless.md), in which this parameter is optional and can be omitted).
 - `options` (optional): an object with embed options ([EmbedOptions](../api/interfaces/EmbedOptions.md)).
 
@@ -76,7 +76,7 @@ The `createPlayground` function throws an error (promise is rejected) in any of
 
 Type: [`(options?: EmbedOptions) => string`](../api/modules.md#getplaygroundurl)
 
-Gets the URL to playground (as a string) from the provided [embed options](#embed-options). This is useful for easily providing links to run code in playgrounds.
+Gets the URL to playground (as a string) from the provided [options](#embed-options). This can be useful for providing links to run code in playgrounds.
 
 Example:
 
@@ -106,15 +106,15 @@ export const getPlaygroundUrlDemo = {html: `<pre><code\nclass="language-markdown
 
 Type: [`EmbedOptions`](../api/interfaces/EmbedOptions.md)
 
-The [`createPlayground`](#createplayground) and [`getPlaygroundUrl`](#getplaygroundurl) functions accept an optional object with the following optional properties:
+The [`createPlayground`](#createplayground) and [`getPlaygroundUrl`](#getplaygroundurl) functions accept an optional object that allows providing different options to the playground. This object can have the following optional properties:
 
 ### `appUrl`
 
 Type: [`string`](../api/interfaces/EmbedOptions.md#appurl)
 
 Default: `"https://livecodes.io/"`
 
-Allows the library to load the playground from a custom URL (e.g. [self-hosted app](../features/self-hosting.md), [permanent URL](../features/permanent-url.md)).
+Allows loading the playground from a custom URL (e.g. a [self-hosted app](../features/self-hosting.md) or a [permanent URL](../features/permanent-url.md)).
 
 If supplied with an invalid URL, an error is thrown.
 
@@ -148,25 +148,25 @@ Type: [`"eager" | "lazy" | "click"`](../api/interfaces/EmbedOptions.md#loading)
 
 Default: `"lazy"`
 
-"eager": The playground loads immediately.
+Sets how the playground loads:
 
-"lazy": A playground embedded low down in the page will not load until the user scrolls so that it approaches the viewport.
-
-"click": The playground does not load automatically. Instead, a "Click-to-load" screen is shown.
+- `"eager"`: The playground loads immediately.
+- `"lazy"`: A playground embedded low down in the page will not load until the user scrolls so that it approaches the viewport.
+- `"click"`: The playground does not load automatically. Instead, a "Click-to-load" screen is shown.
 
 ### `params`
 
 Type: [`UrlQueryParams`](../api/interfaces/EmbedOptions.md#params)
 
-An object that represents [URL Query parameters](../configuration/query-params.md).
+An object that represents [URL Query parameters](../configuration/query-params.md), that can be used to configure the playground.
 
 These 2 snippets produce similar output:
 
 ```js
 import { createPlayground } from 'livecodes';
 
 // use config
-createPlayground('#container1', {
+createPlayground('#container', {
   config: {
     markup: {
       language: 'markdown',
@@ -176,14 +176,14 @@ createPlayground('#container1', {
 });
 
 // use params
-createPlayground('#container2', { params: { md: '# Hello World!' } });
+createPlayground('#container', { params: { md: '# Hello World!' } });
 ```
 
 ### `template`
 
 Type: [`TemplateName`](../api/interfaces/EmbedOptions.md#template)
 
-A [starter template](../features/templates.md) to load.
+A [starter template](../features/templates.md) to load. Allowed valued can be found [here](../api/interfaces/EmbedOptions.md#template).
 
 ### `view`
 
@@ -254,9 +254,9 @@ createPlayground('#container').then(async (playground) => {
 
 Type: [`(shortUrl?: boolean) => Promise<string>`](../api/interfaces/Playground.md#getshareurl)
 
-Gets a [share url](../features/share.md).
+Gets a [share url](../features/share.md) for the current project.
 
-By default, the url is has a long query string representing the compressed config object. If the argument `shortUrl` was set to `true`, a short url is generated.
+By default, the url has a long query string representing the compressed encoded config object. If the argument `shortUrl` was set to `true`, a short url is generated.
 
 ```js
 import { createPlayground } from 'livecodes';
@@ -314,7 +314,7 @@ import { createPlayground } from 'livecodes';
 createPlayground('#container').then(async (playground) => {
   const code = await playground.getCode();
 
-  // source code, language and compiled code are available
+  // source code, language and compiled code for the script editor
   const { content, language, compiled } = code.script;
 
   // result page HTML
@@ -445,7 +445,9 @@ These are the events that can be watched and the description of their callback f
   ) => { remove: () => void }
   ```
 
-- `"code"`: Called when the playground "content" is changed (see [`getCode`](./js-ts.md#getcode) and [`getConfig`](./js-ts.md#getconfig)). This include changes in:
+- `"code"`: Called when the playground "content" is changed (see [`getCode`](./js-ts.md#getcode) and [`getConfig`](./js-ts.md#getconfig)).
+
+  This includes changes in:
 
   - Code (in editors)
   - Editor languages

src/sdk/index.ts

@@ -18,9 +18,10 @@ export type { Code, Config, EmbedOptions, Language, Playground };
 /**
  * Creates a LiveCodes playground.
  *
- * @param {string | HTMLElement} container - The container where the playground will be rendered.
- * @param {EmbedOptions} options - The embed options for the playground (optional).
- * @return {Promise<Playground>} - A promise that resolves to the created playground.
+ * @param {string | HTMLElement} container - `HTMLElement` or a string representing a CSS selector. This is the container where the playground is rendered.
+  If not found, an error is thrown (except in [headless mode](https://livecodes.io/docs/sdk/headless), in which this parameter is optional and can be omitted).
+ * @param {EmbedOptions} options - The [embed options](https://livecodes.io/docs/sdk/js-ts#embed-options) for the playground (optional).
+ * @return {Promise<Playground>} - A promise that resolves to a [`Playground`](https://livecodes.io/docs/api/interfaces/Playground/) object which exposes many [SDK methods](https://livecodes.io/docs/sdk/js-ts/#sdk-methods) that can be used to interact with the playground.
  */
 export async function createPlayground(
   container: string | HTMLElement,
@@ -378,6 +379,13 @@ export async function createPlayground(
   };
 }
 
+/**
+ * Gets the URL to a LiveCodes playground (as a string) from the provided [options](https://livecodes.io/docs/sdk/js-ts#embed-options).
+ * This can be useful for providing links to run code in playgrounds.
+ *
+ * @param {EmbedOptions} options - The [options](https://livecodes.io/docs/sdk/js-ts#embed-options) for the playground.
+ * @return {string} - The URL of the playground (as a string).
+ */
 export function getPlaygroundUrl(options: EmbedOptions = {}): string {
   const { appUrl, params, config, import: x, ...otherOptions } = options;
   const configParam =