docs(web): improve documentation on addKeyboards/addKeyboardsForLanguage

web/docs/engine/guide/adding-keyboards.md

@@ -4,57 +4,80 @@ title: Adding Keyboards
 
 There are multiple ways to add and install keyboards into your KeymanWeb installation.
 
-## Directly linking a local copy
+## Requesting from the Keyman cloud (CDN)
 
-The most efficient way to utilize a keyboard is to obtain a local copy of it and place this copy in a static location on your website. Once this is done, it can be directly linked into KeymanWeb as follows.
-
-```c
-keyman.addKeyboards({
-    id:'us',                  // The keyboard's unique identification code.
-    name:'English',           // The keyboard's user-readable name.
-    language:{
-      id:'en',                // A BCP 47 code uniquely identifying the language.
-      name:'English (US)'     // The language's name.
-    },
-    filename:'./us-1.0.js'    // A valid path to the compiled *.js file representing the keyboard.
-});
-```
+The easiest way to utilize a keyboard is to request it from the Keyman cloud.
 
-Custom fonts may also be utilized via the `language.font` property. For example:
+### Requested from the CDN by keyboard name
 
-```c
-font:{
-    family:'LaoWeb',
-    source:['../font/saysettha_web.ttf','../font/saysettha_web.woff','../font/saysettha_web.eot']
-}
+To obtain a specific keyboard by name or by keyboard name and language code as a pair, see the
+following:
+
+```typescript
+await keyman.addKeyboards('khmer_angkor','sil_euro_latin@sv','sil_euro_latin@no')
 ```
 
-## Requested from the CDN by language name
+This will install three keyboards - the Khmer Angkor one for Khmer and two copies
+of the EuroLatin keyboard - one for Swedish and one for Norwegian.
 
-To obtain the default Keyman keyboard for a given language, call the following function.
+### Requested from the CDN by language name
 
-```c
-keyman.addKeyboardsForLanguage('Dzongkha');
+To obtain the default Keyman keyboard for a given language, call the following function:
+
+```typescript
+await keyman.addKeyboardsForLanguage('Dzongkha');
 ```
 
-This example would find the default keyboard for the Dzongkha language. This method will fail if the name doesn't perfectly match any language found in the CDN's repository.
+This example would find the default keyboard for the Dzongkha language. This method will fail if
+the name doesn't perfectly match any language found in the CDN's repository.
 
 Alternatively, languages may be looked up via their BCP 47 language code as follows:
 
-```c
-keyman.addKeyboards('@he')
+```typescript
+await keyman.addKeyboards('@he')
 ```
 
-The `@` prefix indicates the use of the BCP 47 language code, which in this case corresponds with Hebrew.
+The `@` prefix indicates the use of the BCP 47 language code, which in this case corresponds with
+Hebrew.
 
-## Requested from the CDN by keyboard name
+To add all keyboards for a language at once, `$` can be appended to the language
+name or language code:
 
-To obtain a specific keyboard by name or by keyboard name and language code as a pair, see the following:
+```typescript
+await keyman.addKeyboards('@fr$');
+// or
+await keyman.addKeyboardsForLanguage('French$');
+```
 
-```c
-keyman.addKeyboards('french','sil_euro_latin@sv','sil_euro_latin@no')
+## Directly linking a local copy
+
+The most efficient way to utilize a keyboard is to obtain a local copy of it and place this copy
+in a static location on your website. Once this is done, it can be directly linked into KeymanWeb
+as follows:
+
+```typescript
+await keyman.addKeyboards({
+  id: 'us',                  // The keyboard's unique identification code.
+  name: 'English',           // The keyboard's user-readable name.
+  languages: {
+    id: 'en',                // A BCP 47 code uniquely identifying the language.
+    name: 'English (US)'     // The language's name.
+  },
+  filename: './us.js'    // A valid path to the compiled *.js file representing the keyboard.
+});
 ```
 
-This will install three keyboards - one for French (named, quite simply, "French") and two copies of the EuroLatin keyboard - one for Swedish and one for Norwegian.
+Custom fonts may also be utilized via the `languages.font` property. For example:
+
+```typescript
+languages:{
+  id:'lo',
+  name:'Lao',
+  font:{
+    family:'LaoWeb',
+    source:['../font/saysettha_web.ttf','../font/saysettha_web.woff']
+  }
+}
+```
 
 [Previous: What is a Keyboard?](what-is-a-keyboard) | [Next: Additional Examples](examples/)

web/docs/engine/reference/core/addKeyboards.md

@@ -4,12 +4,12 @@ title: addKeyboards function
 
 ## Summary
 
-Adds keyboards to KeymanWeb.
+Adds keyboards to KeymanWeb. Note that this is an asynchronous operation.
 
 ## Syntax
 
 ```js
-keyman.addKeyboards(spec[, spec...])
+await keyman.addKeyboards(spec[, spec...])
 ```
 
 ### Parameters
@@ -54,6 +54,9 @@ The string format is one of the following:
 The keyboard catalogue is online at
 [https://keyman.com/developer/keymanweb/keyboards](https://keyman.com/developer/keymanweb/keyboards).
 
+If the BCP47 language code is suffixed with `$` (e.g. `@fr$`) and no specific keyboard is
+requested, all keyboards for that language code will be loaded.
+
 ### Using an `object`
 
 When keyboard spec is an object, then more parameters can be specified,

web/docs/engine/reference/core/addKeyboardsForLanguage.md

@@ -4,12 +4,13 @@ title: addKeyboardsForLanguage function
 
 ## Summary
 
-Add default or all keyboards for a given language to KeymanWeb.
+Add default or all keyboards for a given language to KeymanWeb. Note that this is an asynchronous
+operation.
 
 ## Syntax
 
 ```js
-keyman.addKeyboardsForLanguage(spec[, spec...])
+await keyman.addKeyboardsForLanguage(spec[, spec...])
 ```
 
 ### Parameters
@@ -31,6 +32,7 @@ The promise is an array containing the following:
 
 * successfully registered keyboard objects which define some or all of these
   [properties](../keyboard_properties)
+* [ErrorStub](../keyboard_registration_errors) objects for keyboards that failed to register
 
 ## Description
 

web/src/app/browser/src/keymanEngine.ts

@@ -345,7 +345,7 @@ export class KeymanEngine extends KeymanEngineBase<BrowserConfiguration, Context
    *
    * See https://help.keyman.com/developer/engine/web/current-version/reference/core/addKeyboards
    */
-  public addKeyboards(...args: any[]): Promise<(KeyboardStub|ErrorStub)[]> {
+  public async addKeyboards(...args: any[]): Promise<(KeyboardStub|ErrorStub)[]> {
     return this.config.deferForInitialization.then(() => {
       if (!args || !args[0] || args[0].length == 0) {
         // Get the cloud keyboard catalog
@@ -373,7 +373,7 @@ export class KeymanEngine extends KeymanEngineBase<BrowserConfiguration, Context
    *
    * See https://help.keyman.com/developer/engine/web/current-version/reference/core/addKeyboardsForLanguage
    **/
-  public addKeyboardsForLanguage(arg: string[]|string) : Promise<(KeyboardStub|ErrorStub)[]> {
+  public async addKeyboardsForLanguage(arg: string[]|string) : Promise<(KeyboardStub|ErrorStub)[]> {
     return this.config.deferForInitialization.then(() => {
       if (typeof arg === 'string') {
         return this.keyboardRequisitioner.addLanguageKeyboards(arg.split(',').map(item => item.trim()));
@@ -497,7 +497,7 @@ export class KeymanEngine extends KeymanEngineBase<BrowserConfiguration, Context
    *
    * See https://help.keyman.com/developer/engine/web/current-version/reference/core/removeKeyboards
    */
-  public removeKeyboards(...x: string[]) {
+  public removeKeyboards(...x: string[]): boolean {
     for(let i=0; i < x.length; i++) {
       // This will completely forget the keyboard, requiring an async load operation to restore it again.
       // `true` is responsible for this & is required to pass a variable-store unit test.