jssm 5.65.2 → 5.65.3

package/jssm.d.ts

@@ -51,13 +51,117 @@ declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind;
 declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
 /*********
  *
- *  Internal convenience method for alting out an object as the options call.
- *  Not generally meant for external use.
+ *  This method wraps the parser call that comes from the peg grammar,
+ *  {@link parse}.  Generally neither this nor that should be used directly
+ *  unless you mean to develop plugins or extensions for the machine.
+ *
+ *  Parses the intermediate representation of a compiled string down to a
+ *  machine configuration object.  If you're using this (probably don't,) you're
+ *  probably also using {@link compile} and {@link Machine.constructor}.
+ *
+ *  ```typescript
+ *  import { parse, compile, Machine } from './jssm';
+ *
+ *  const intermediate = wrap_parse('a -> b;', {});
+ *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
+ *
+ *  const cfg = compile(intermediate);
+ *  // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] }
+ *
+ *  const machine = new Machine(cfg);
+ *  // Machine { _instance_name: undefined, _state: 'a', ...
+ *  ```
+ *
+ *  This method is mostly for plugin and intermediate tool authors, or people
+ *  who need to work with the machine's intermediate representation.
+ *
+ *  # Hey!
+ *
+ *  Most people looking at this want either the `sm` operator or method `from`,
+ *  which perform all the steps in the chain.  The library's author mostly uses
+ *  operator `sm`, and mostly falls back to `.from` when needing to parse
+ *  strings dynamically instead of from template literals.
+ *
+ *  ```typescript
+ *  import { sm } from './jssm';
+ *
+ *  const switch = sm`on <=> off;`;
+ *  ```
+ *
+ *  &hellip; or &hellip;
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const toggle = jssm.from('up <=> down;');
+ *  ```
+ *
+ *  `wrap_parse` itself is an internal convenience method for alting out an
+ *  object as the options call.  Not generally meant for external use.
  *
  */
 declare function wrap_parse(input: string, options?: Object): any;
+/*********
+ *
+ *  Compile a machine's JSON intermediate representation to a config object.  If
+ *  you're using this (probably don't,) you're probably also using
+ *  {@link parse} to get the IR, and the object constructor
+ *  {@link Machine.construct} to turn the config object into a workable machine.
+ *
+ *  ```typescript
+ *  import { parse, compile, Machine } from './jssm';
+ *
+ *  const intermediate = parse('a -> b;');
+ *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
+ *
+ *  const cfg = compile(intermediate);
+ *  // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] }
+ *
+ *  const machine = new Machine(cfg);
+ *  // Machine { _instance_name: undefined, _state: 'a', ...
+ *  ```
+ *
+ *  This method is mostly for plugin and intermediate tool authors, or people
+ *  who need to work with the machine's intermediate representation.
+ *
+ *  # Hey!
+ *
+ *  Most people looking at this want either the `sm` operator or method `from`,
+ *  which perform all the steps in the chain.  The library's author mostly uses
+ *  operator `sm`, and mostly falls back to `.from` when needing to parse
+ *  strings dynamically instead of from template literals.
+ *
+ *  ```typescript
+ *  import { sm } from './jssm';
+ *
+ *  const switch = sm`on <=> off;`;
+ *  ```
+ *
+ *  &hellip; or &hellip;
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const toggle = jssm.from('up <=> down;');
+ *  ```
+ *
+ */
 declare function compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT>;
+/*********
+ *
+ *  An internal convenience wrapper for parsing then compiling a machine string.
+ *  Not generally meant for external use.  Please see {@link compile} or
+ *  {@link sm}.
+ *
+ */
 declare function make<mDT>(plan: string): JssmGenericConfig<mDT>;
+/*********
+ *
+ *  An internal method meant to take a series of declarations and fold them into
+ *  a single multi-faceted declaration, in the process of building a state.  Not
+ *  generally meant for external use.
+ *
+ */
 declare function transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration;
 declare class Machine<mDT> {
     _state: StateType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.65.2",
+  "version": "5.65.3",
   "engines": {
     "node": ">=10.0.0"
   },