Improve doc comments (#207)

* Improve doc comments ahead of new version

Author: dyedgreen

src/db.ts

@@ -142,6 +142,14 @@ export class DB {
    * const rows = db.query<[string, number]>("SELECT name, age FROM people WHERE city = ?", [city]);
    * // rows = [["Peter Parker", 21], ...]
    * ```
+   *
+   * ```typescript
+   * const rows = db.query<[string, number]>(
+   *   "SELECT name, age FROM people WHERE city = :city",
+   *   { city },
+   *  );
+   * // rows = [["Peter Parker", 21], ...]
+   * ```
    */
   query<R extends Row = Row>(
     sql: string,
@@ -168,6 +176,14 @@ export class DB {
    * const rows = db.queryEntries<{ name: string, age: number }>("SELECT name, age FROM people");
    * // rows = [{ name: "Peter Parker", age: 21 }, ...]
    * ```
+   *
+   * ```typescript
+   * const rows = db.queryEntries<{ name: string, age: number }>(
+   *   "SELECT name, age FROM people WHERE age >= :minAge",
+   *   { minAge },
+   *  );
+   * // rows = [{ name: "Peter Parker", age: 21 }, ...]
+   * ```
    */
   queryEntries<O extends RowObject = RowObject>(
     sql: string,
@@ -205,15 +221,15 @@ export class DB {
    * to specify precise types for returned data and
    * query parameters.
    *
-   * The first type parameter `R` indicates the tuple type
-   * for rows returned by the query.
+   * + The first type parameter `R` indicates the tuple type
+   *   for rows returned by the query.
    *
-   * The second type parameter `O` indicates the record type
-   * for rows returned as entries (mappings from column names
-   * to values).
+   * + The second type parameter `O` indicates the record type
+   *   for rows returned as entries (mappings from column names
+   *   to values).
    *
-   * The third type parameter `P` indicates the type this query
-   * accepts as parameters.
+   * + The third type parameter `P` indicates the type this query
+   *   accepts as parameters.
    *
    * Note, that the correctness of those types must
    * be guaranteed by the caller of this function.
@@ -226,7 +242,9 @@ export class DB {
    *   { name: string, age: number },
    *   { city: string },
    *  >("SELECT name, age FROM people WHERE city = :city");
+   *
    * // use query ...
+   *
    * query.finalize();
    * ```
    */
@@ -318,9 +336,9 @@ export class DB {
    * the database is no longer used to avoid leaking
    * open file descriptors.
    *
-   * If `force` is specified, any active `PreparedQuery`
-   * will be finalized. Otherwise, this throws if there
-   * are active queries.
+   * If `force = true` is passed, any non-finalized
+   * `PreparedQuery` objects will be finalized. Otherwise,
+   * this throws if there are active queries.
    *
    * `close` may safely be called multiple
    * times.

src/error.ts

@@ -3,7 +3,7 @@ import { getStr } from "./wasm.ts";
 import { Status } from "./constants.ts";
 
 /**
- * Errors which can be thrown while interacting with
+ * Errors which can occur while interacting with
  * a database.
  */
 export class SqliteError extends Error {

src/query.ts

@@ -89,8 +89,23 @@ export type QueryParameterSet =
  * Name of a column in a database query.
  */
 export interface ColumnName {
+  /**
+   * Name of the returned column.
+   */
   name: string;
+  /**
+   * Name of the database column that stores
+   * the data returned from this query.
+   *
+   * This might be different from `name` if a
+   * columns was renamed using e.g. as in
+   * `SELECT foo AS bar FROM table`.
+   */
   originName: string;
+  /**
+   * Name of the table that stores the data
+   * returned from this query.
+   */
   tableName: string;
 }
 
@@ -118,10 +133,7 @@ export class PreparedQuery<
   private _finalized: boolean;
 
   /**
-   * A prepared query which can be executed many
-   * times.
-   *
-   * The constructor should never be used directly.
+   * This constructor should never be used directly.
    * Instead a prepared query can be obtained by
    * calling `DB.prepareQuery`.
    */
@@ -321,21 +333,32 @@ export class PreparedQuery<
    * rows into memory and hence allows to process a large
    * number of rows.
    *
-   * # Example:
+   * Calling `iter`, `all`, or `first` invalidates any iterators
+   * previously returned from this prepared query.
+   *
+   * # Examples
+   *
    * ```typescript
    * const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people");
    * for (const [id, name] of query.iter()) {
    *   // ...
    * }
    * ```
    *
-   * Calling `iter` invalidates any iterators previously returned
-   * from this prepared query. Using an invalidated iterator is a bug.
-   *
    * To avoid SQL injection, user-provided values
    * should always be passed to the database through
    * a query parameter.
    *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id FROM people WHERE name = ?");
+   * preparedQuery.iter([name]);
+   * ```
+   *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id FROM people WHERE name = :name");
+   * preparedQuery.iter({ name });
+   * ```
+   *
    * See `QueryParameterSet` for documentation on
    * how values can be bound to SQL statements.
    *
@@ -357,6 +380,15 @@ export class PreparedQuery<
   /**
    * Like `iter` except each row is returned
    * as an object containing key-value pairs.
+   *
+   * # Examples
+   *
+   * ```typescript
+   * const query = db.prepareQuery<_, { id: number, name: string }>("SELECT id, name FROM people");
+   * for (const { id, name } of query.iter()) {
+   *   // ...
+   * }
+   * ```
    */
   iterEntries(params?: P): RowsIterator<O> {
     this.iter(params);
@@ -401,14 +433,28 @@ export class PreparedQuery<
    * and returns an array containing all resulting
    * rows.
    *
-   * Calling `all` invalidates any iterators
-   * previously returned by calls to `iter`.
-   * Using an invalidated iterator is a bug.
+   * # Examples
+   *
+   * ```typescript
+   * const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people");
+   * const rows = query.all();
+   * // [[1, "Peter"], ...]
+   * ```
    *
    * To avoid SQL injection, user-provided values
    * should always be passed to the database through
    * a query parameter.
    *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id FROM people WHERE name = ?");
+   * preparedQuery.all([name]);
+   * ```
+   *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id FROM people WHERE name = :name");
+   * preparedQuery.all({ name });
+   * ```
+   *
    * See `QueryParameterSet` for documentation on
    * how values can be bound to SQL statements.
    *
@@ -432,6 +478,14 @@ export class PreparedQuery<
   /**
    * Like `all` except each row is returned
    * as an object containing key-value pairs.
+   *
+   * # Examples
+   *
+   * ```typescript
+   * const query = db.prepareQuery<_, { id: number, name: string }>("SELECT id, name FROM people");
+   * const rows = query.all();
+   * // [{ id: 1, name: "Peter" }, ...]
+   * ```
    */
   allEntries(params?: P): Array<O> {
     return this.all(params).map((row) => this.makeRowObject(row));
@@ -443,14 +497,34 @@ export class PreparedQuery<
    * `undefined` when there are no rows returned
    * by the query.
    *
-   * Calling `first` invalidates any iterators
-   * previously returned by calls to `iter`.
-   * Using an invalidated iterator is a bug.
+   * # Examples
+   *
+   * ```typescript
+   * const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people");
+   * const person = query.first();
+   * // [1, "Peter"]
+   * ```
+   *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id, name FROM people WHERE name = ?");
+   * const person = query.first(["not a name"]);
+   * // undefined
+   * ```
    *
    * To avoid SQL injection, user-provided values
    * should always be passed to the database through
    * a query parameter.
    *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id FROM people WHERE name = ?");
+   * preparedQuery.first([name]);
+   * ```
+   *
+   * ```typescript
+   * const query = db.prepareQuery("SELECT id FROM people WHERE name = :name");
+   * preparedQuery.first({ name });
+   * ```
+   *
    * See `QueryParameterSet` for documentation on
    * how values can be bound to SQL statements.
    *
@@ -479,14 +553,22 @@ export class PreparedQuery<
   /**
    * Like `first` except the row is returned
    * as an object containing key-value pairs.
+   *
+   * # Examples
+   *
+   * ```typescript
+   * const query = db.prepareQuery<_, { id: number, name: string }>("SELECT id, name FROM people");
+   * const person = query.first();
+   * // { id: 1, name: "Peter" }
+   * ```
    */
   firstEntry(params?: P): O | undefined {
     const row = this.first(params);
     return row === undefined ? undefined : this.makeRowObject(row);
   }
 
   /**
-   * Deprecated, prefer `first`.
+   * **Deprecated:** prefer `first`.
    */
   one(params?: P): R {
     const rows = this.all(params);
@@ -501,7 +583,7 @@ export class PreparedQuery<
   }
 
   /**
-   * Deprecated, prefer `firstEntry`.
+   * **Deprecated:** prefer `firstEntry`.
    */
   oneEntry(params?: P): O {
     return this.makeRowObject(this.one(params));
@@ -516,16 +598,23 @@ export class PreparedQuery<
    * rows returned by a query are not needed or
    * the query does not return any rows.
    *
-   * Calling `execute` invalidates any iterators
-   * previously returned by calls to `iter`.
-   * Using an invalidated iterator is a bug.
+   * # Examples
    *
-   * To avoid SQL injection, user-provided values
-   * should always be passed to the database through
-   * a query parameter.
+   * ```typescript
+   * const query = db.prepareQuery<_, _, [string]>("INSERT INTO people (name) VALUES (?)");
+   * query.execute(["Peter"]);
+   * ```
+   *
+   * ```typescript
+   * const query = db.prepareQuery<_, _, { name: string }>("INSERT INTO people (name) VALUES (:name)");
+   * query.execute({ name: "Peter" });
+   * ```
    *
    * See `QueryParameterSet` for documentation on
    * how values can be bound to SQL statements.
+   *
+   * See `QueryParameter` for documentation on how
+   * values are returned from the database.
    */
   execute(params?: P) {
     this.startQuery(params);
@@ -544,10 +633,11 @@ export class PreparedQuery<
    * to avoid leaking resources.
    *
    * After a prepared query has been finalized,
-   * trying to call `iter`, `all`, `one`,
-   * `execute`, or `columns`, or using iterators which where
-   * previously obtained from the finalized query
-   * is a bug.
+   * calls to `iter`, `all`, `first`, `execute`,
+   * or `columns` will fail.
+   *
+   * Using iterators which were previously returned
+   * from the finalized query will fail.
    *
    * `finalize` may safely be called multiple
    * times.