Merge branch 'main' into docusaurus

src/lib/_format.ts

@@ -3,21 +3,22 @@ import { BasicTriple, Branch, Node } from './types';
 import { lstrip } from './utils';
 
 /**
- * Format *tree* into a PENMAN string.
+ * Format a `Tree` object into a PENMAN string.
  *
- * Args:
- *    tree: a Tree object
- *    indent: how to indent formatted strings
- *    compact: if ``True``, put initial attributes on the first line
- * Returns:
- *    the PENMAN-serialized string of the Tree *t*
- * Example:
- *     >>> import penman
- *     >>> print(penman.format(
- *     ...     ('b', [('/', 'bark-01'),
- *     ...            (':ARG0', ('d', [('/', 'dog')]))])))
- *     (b / bark-01
- *       :ARG0 (d / dog))
+ * @param tree - A Tree object.
+ * @param indent - How to indent formatted strings.
+ * @param compact - If `true`, put initial attributes on the first line.
+ * @returns The PENMAN-serialized string of the `Tree` object.
+ * @example
+ * import { format } from 'penman-js';
+ *
+ * console.log(format(
+ *   ['b', [['/', 'bark-01'],
+ *          [':ARG0', ['d', [['/', 'dog']]]]]
+ *   ]
+ * ));
+ * // (b / bark-01
+ * //   :ARG0 (d / dog))
  */
 export const format = (
   tree: Tree | Node,
@@ -36,21 +37,21 @@ export const format = (
 };
 
 /**
- * Return the formatted triple conjunction of *triples*.
+ * Return the formatted triple conjunction of `triples`.
+ *
+ * @param triples - An iterable of triples.
+ * @param indent - How to indent formatted strings.
+ * @returns The serialized triple conjunction of `triples`.
+ * @example
+ * import { decode, formatTriples } from 'penman-js';
  *
- * Args:
- *     triples: an iterable of triples
- *     indent: how to indent formatted strings
- * Returns:
- *     the serialized triple conjunction of *triples*
- * Example:
- *     >>> import penman
- *     >>> g = penman.decode('(b / bark-01 :ARG0 (d / dog))')
- *     >>> print(penman.format_triples(g.triples))
- *     instance(b, bark-01) ^
- *     ARG0(b, d) ^
- *     instance(d, dog)
+ * const g = decode('(b / bark-01 :ARG0 (d / dog))');
+ * console.log(formatTriples(g.triples));
+ * // instance(b, bark-01) ^
+ * // ARG0(b, d) ^
+ * // instance(d, dog)
  */
+
 export const formatTriples = (
   triples: BasicTriple[],
   indent = true,

src/lib/_lexer.ts

@@ -108,9 +108,7 @@ export class TokenIterator {
   /**
    * Advance the iterator and return the next token.
    *
-   * Raises:
-   *    StopIteration
-   *       If the iterator is already exhausted.
+   * @throws {Error} If the iterator is already exhausted.
    */
   next(): IteratorResult<Token, Token> {
     const current = this._next;
@@ -126,14 +124,13 @@ export class TokenIterator {
   }
 
   /**
-   * Return the next token if its type is in *choices*.
+   * Return the next token if its type is in `choices`.
    *
    * The iterator is advanced if successful.
    *
-   * Raises:
-   *   ~penman.exceptions.DecodeError
-   *      If the next token type is not in *choices*.
+   * @throws {DecodeError} If the next token type is not in `choices`.
    */
+
   expect(...choices: string[]): Token {
     const token = this.next();
     if (token.done) {
@@ -180,18 +177,14 @@ export class TokenIterator {
 }
 
 /**
- * Yield PENMAN tokens matched in *lines*.
- *
- * By default, this lexes strings in *lines* using the basic pattern
- * for PENMAN graphs. If *pattern* is given, it is used for lexing
- * instead.
+ * Yield PENMAN tokens matched in `lines`.
  *
- * Args:
- *   lines: iterable of lines to lex
- *   pattern: pattern to use for lexing instead of the default ones
+ * By default, this function lexes strings in `lines` using the basic pattern
+ * for PENMAN graphs. If `pattern` is provided, it is used for lexing instead.
  *
- * Returns:
- *   A :class:`TokenIterator` object
+ * @param lines - An iterable of lines to lex.
+ * @param pattern - The pattern to use for lexing instead of the default ones.
+ * @returns A `TokenIterator` object.
  */
 export const lex = (
   lines: Iterable<string> | string,

src/lib/_parse.ts

@@ -4,37 +4,40 @@ import { Tree } from './tree';
 import { BasicTriple, Branch, Node, Target } from './types';
 
 /**
- * Parse PENMAN-notation string *s* into its tree structure.
+ * Parse a PENMAN-notation string `s` into its tree structure.
  *
- * Args:
- *    s: a string containing a single PENMAN-serialized graph
- * Returns:
- *   The tree structure described by *s*.
- * Example:
- *  >>> import penman
- *  >>> penman.parse('(b / bark-01 :ARG0 (d / dog))')  // noqa
- *  Tree(('b', [('/', 'bark-01'), (':ARG0', ('d', [('/', 'dog')]))]))
+ * @param s - A string containing a single PENMAN-serialized graph.
+ * @returns The tree structure described by `s`.
+ * @example
+ * import { parse } from 'penman-js';
+ *
+ * const tree = parse('(b / bark-01 :ARG0 (d / dog))');
+ * console.log(tree);
+ *
+ * // Tree(['b', [['/', 'bark-01'], [':ARG0', ['d', [['/', 'dog']]]]])
  */
+
 export const parse = (s: string): Tree => {
   const tokens = lex(s, PENMAN_RE);
   return _parse(tokens);
 };
 
 /**
- * Yield trees parsed from *lines*.
+ * Yield trees parsed from `lines`.
+ *
+ * @param lines - A string or open file with PENMAN-serialized graphs.
+ * @returns The `Tree` object described in `lines`.
+ * @example
+ * import { iterparse } from 'penman-js';
  *
- * Args:
- *   lines: a string or open file with PENMAN-serialized graphs
- * Returns:
- *   The :class:`~penman.tree.Tree` object described in *lines*.
- * Example:
- *   >>> import penman
- *   >>> for t in penman.iterparse('(a / alpha) (b / beta)'):
- *   ...     print(repr(t))
- *   ...
- *   Tree(('a', [('/', 'alpha')]))
- *   Tree(('b', [('/', 'beta')]))
+ * for (const t of iterparse('(a / alpha) (b / beta)')) {
+ *   console.log(t);
+ * }
+ *
+ * // Tree(['a', [['/', 'alpha']]])
+ * // Tree(['b', [['/', 'beta']]])
  */
+
 export function* iterparse(
   lines: Iterable<string> | string,
 ): IterableIterator<Tree> {
@@ -45,19 +48,24 @@ export function* iterparse(
 }
 
 /**
- * Parse a triple conjunction from *s*.
+ * Parse a triple conjunction from `s`.
  *
- * Example:
- *   >>> import penman
- *   >>> for triple in penman.parse_triples('''
- *   ...         instance(b, bark) ^
- *   ...         ARG0(b, d) ^
- *   ...         instance(d, dog)'''):
- *   ...     print(triple)
- *   ('b', ':instance', 'bark')
- *   ('b', ':ARG0', 'd')
- *   ('d', ':instance', 'dog')
+ * @param s - A string containing the triple conjunction.
+ * @returns An iterator yielding triples.
+ * @example
+ * import { parseTriples } from 'penman-js';
+ *
+ * for (const triple of parseTriples(`
+ *          instance(b, bark) ^
+ *          ARG0(b, d) ^
+ *          instance(d, dog)`)) {
+ *   console.log(triple);
+ *   // ['b', ':instance', 'bark']
+ *   // ['b', ':ARG0', 'd']
+ *   // ['d', ':instance', 'dog']
+ * }
  */
+
 export const parseTriples = (s: string): BasicTriple[] => {
   const tokens = lex(s, TRIPLE_RE);
   return _parseTriples(tokens);

src/lib/codec.ts

@@ -226,13 +226,11 @@ export function _encode(
 }
 
 /**
- * Deserialize a list of PENMAN-encoded graphs from *source*.
-
- * Args:
- *     source: a filename to read from
- *     model: the model used for interpreting the graph
- * Returns:
- *     a list of Graph objects
+ * Deserialize a list of PENMAN-encoded graphs from `source`.
+ *
+ * @param source - A filename to read from.
+ * @param model - The model used for interpreting the graph.
+ * @returns A list of `Graph` objects.
  */
 export function _load(
   source: string,
@@ -247,28 +245,25 @@ export function _load(
 }
 
 /**
- * Deserialize a list of PENMAN-encoded graphs from *string*.
+ * Deserialize a list of PENMAN-encoded graphs from a string.
  *
- * Args:
- *     string: a string containing graph data
- *     model: the model used for interpreting the graph
- * Returns:
- *     a list of Graph objects
+ * @param string - A string containing graph data.
+ * @param model - The model used for interpreting the graph.
+ * @returns A list of `Graph` objects.
  */
 export function _loads(string: string, model?: Model): Graph[] {
   const codec = new PENMANCodec(model);
   return Array.from(codec.iterdecode(string));
 }
 
 /**
- * Serialize each graph in *graphs* to PENMAN and write to *file*.
+ * Serialize each graph in `graphs` to PENMAN notation and write to `file`.
  *
- * Args:
- *     graphs: an iterable of Graph objects
- *     file: a filename to write to
- *     model: the model used for interpreting the graph
- *     indent: how to indent formatted strings
- *     compact: if ``True``, put initial attributes on the first line
+ * @param graphs - An iterable of Graph objects.
+ * @param file - A filename to write to.
+ * @param model - The model used for interpreting the graph.
+ * @param indent - How to indent formatted strings.
+ * @param compact - If `true`, put initial attributes on the first line.
  */
 export function _dump(
   graphs: Graph[],
@@ -304,15 +299,13 @@ export function _dumpStream(
 }
 
 /**
- * Serialize each graph in *graphs* to the PENMAN format.
+ * Serialize each graph in `graphs` to the PENMAN format.
  *
- * Args:
- *     graphs: an iterable of Graph objects
- *     model: the model used for interpreting the graph
- *     indent: how to indent formatted strings
- *     compact: if ``True``, put initial attributes on the first line
- * Returns:
- *     the string of serialized graphs
+ * @param graphs - An iterable of Graph objects.
+ * @param model - The model used for interpreting the graph.
+ * @param indent - How to indent formatted strings.
+ * @param compact - If `true`, put initial attributes on the first line.
+ * @returns The string of serialized graphs.
  */
 export function _dumps(
   graphs: Graph[],