(core) Update app/plugin/ documentation comments to improve generated docs

Summary:
- Move CellValue documentation to CellValue and add an example for each type.
- Link to CellValue from places that mention it.
- Update deprecated [[LINK]] syntax to a supported {@link} one, in a way that
  does not change generated documentation.

- Also fix auto-pick-ports script used in tests (which had a bug causing occasional test failures), and add a test for it.

Test Plan: No code changes for documentation changes. New test for auto-pick-ports.

Reviewers: georgegevoian

Reviewed By: georgegevoian

Differential Revision: https://phab.getgrist.com/D4162

app/plugin/GristAPI.ts

@@ -118,7 +118,7 @@ export interface GristDocAPI {
   listTables(): Promise<string[]>;
 
   /**
-   * Returns a complete table of data as [[GristData.RowRecords]], including the
+   * Returns a complete table of data as {@link GristData.RowRecords | GristData.RowRecords}, including the
    * 'id' column. Do not modify the returned arrays in-place, especially if used
    * directly (not over RPC).
    */
@@ -142,18 +142,18 @@ export interface GristDocAPI {
 /**
  * Options for functions which fetch data from the selected table or record:
  *
- * - [[onRecords]]
+ * - {@link onRecords}
- * - [[onRecord]]
+ * - {@link onRecord}
- * - [[fetchSelectedRecord]]
+ * - {@link fetchSelectedRecord}
- * - [[fetchSelectedTable]]
+ * - {@link fetchSelectedTable}
- * - [[GristView.fetchSelectedRecord]]
+ * - {@link GristView.fetchSelectedRecord | GristView.fetchSelectedRecord}
- * - [[GristView.fetchSelectedTable]]
+ * - {@link GristView.fetchSelectedTable | GristView.fetchSelectedTable}
  *
  * The different methods have different default values for `keepEncoded` and `format`.
  **/
 export interface FetchSelectedOptions {
   /**
-   * - `true`: the returned data will contain raw `CellValue`s.
+   * - `true`: the returned data will contain raw {@link GristData.CellValue}'s.
    * - `false`: the values will be decoded, replacing e.g. `['D', timestamp]` with a moment date.
    */
   keepEncoded?: boolean;
@@ -178,7 +178,8 @@ export interface FetchSelectedOptions {
  */
 export interface GristView {
   /**
-   * Like [[GristDocAPI.fetchTable]], but gets data for the custom section specifically, if there is any.
+   * Like {@link GristDocAPI.fetchTable | GristDocAPI.fetchTable},
+   * but gets data for the custom section specifically, if there is any.
    * By default, `options.keepEncoded` is `true` and `format` is `columns`.
    */
   fetchSelectedTable(options?: FetchSelectedOptions): Promise<any>;

app/plugin/GristData.ts

@@ -1,5 +1,5 @@
 /**
- * Letter codes for CellValue types encoded as [code, args...] tuples.
+ * Letter codes for {@link CellValue} types encoded as [code, args...] tuples.
  */
 export enum GristObjCode {
   List            = 'L',
@@ -19,14 +19,6 @@ export enum GristObjCode {
 
 /**
  * Possible types of cell content.
- */
-export type CellValue = number|string|boolean|null|[GristObjCode, ...unknown[]];
-export interface BulkColValues { [colId: string]: CellValue[]; }
-
-/**
- * Map of column ids to `CellValue`s.
- *
- * ### CellValue
  *
  * Each `CellValue` may either be a primitive (e.g. `true`, `123`, `"hello"`, `null`)
  * or a tuple (JavaScript Array) representing a Grist object. The first element of the tuple
@@ -38,18 +30,25 @@ export interface BulkColValues { [colId: string]: CellValue[]; }
  *
  * | Code | Type           |
  * | ---- | -------------- |
- * | L    | List           |
+ * | `L`  | List, e.g. `["L", "foo", "bar"]` or `["L", 1, 2]` |
- * | l    | LookUp         |
+ * | `l`  | LookUp, as `["l", value, options]` |
- * | O    | Dict           |
+ * | `O`  | Dict, as `["O", {key: value, ...}]` |
- * | D    | DateTime       |
+ * | `D`  | DateTimes, as `["D", timestamp, timezone]`, e.g. `["D", 1704945919, "UTC"]` |
- * | d    | Date           |
+ * | `d`  | Date, as `["d", timestamp]`, e.g. `["d", 1704844800]` |
- * | C    | Censored       |
+ * | `C`  | Censored, as `["C"]` |
- * | R    | Reference      |
+ * | `R`  | Reference, as `["R", table_id, row_id]`, e.g. `["R", "People", 17]` |
- * | r    | ReferenceList  |
+ * | `r`  | ReferenceList, as `["r", table_id, row_id_list]`, e.g. `["r", "People", [1,2]]` |
- * | E    | Exception      |
+ * | `E`  | Exception, as `["E", name, ...]`, e.g. `["E", "ValueError"]` |
- * | P    | Pending        |
+ * | `P`  | Pending, as `["P"]` |
- * | U    | Unmarshallable |
+ * | `U`  | Unmarshallable, as `["U", text_representation]` |
- * | V    | Version        |
+ * | `V`  | Version, as `["V", version_obj]` |
+ */
+export type CellValue = number|string|boolean|null|[GristObjCode, ...unknown[]];
+
+export interface BulkColValues { [colId: string]: CellValue[]; }
+
+/**
+ * Map of column ids to {@link CellValue}'s.
  */
 export interface RowRecord {
   id: number;
@@ -57,33 +56,8 @@ export interface RowRecord {
 }
 
 /**
- * Map of column ids to `CellValue` arrays, where array indexes correspond to
+ * Map of column ids to {@link CellValue} arrays, where array indexes correspond to
  * rows.
- *
- * ### CellValue
- *
- * Each `CellValue` may either be a primitive (e.g. `true`, `123`, `"hello"`, `null`)
- * or a tuple (JavaScript Array) representing a Grist object. The first element of the tuple
- * is a string character representing the object code. For example, `["L", "foo", "bar"]`
- * is a `CellValue` of a Choice List column, where `"L"` is the type, and `"foo"` and
- * `"bar"` are the choices.
- *
- * ### Grist Object Types
- *
- * | Code | Type           |
- * | ---- | -------------- |
- * | L    | List           |
- * | l    | LookUp         |
- * | O    | Dict           |
- * | D    | DateTime       |
- * | d    | Date           |
- * | C    | Censored       |
- * | R    | Reference      |
- * | r    | ReferenceList  |
- * | E    | Exception      |
- * | P    | Pending        |
- * | U    | Unmarshallable |
- * | V    | Version        |
  */
 export interface RowRecords {
   id: number[];

app/plugin/grist-plugin-api.ts

@@ -98,12 +98,12 @@ export const sectionApi = rpc.getStub<CustomSectionAPI>('CustomSectionAPI', chec
 export const commandApi = rpc.getStub<any>('CommandAPI');
 
 /**
- * Shortcut for [[GristView.allowSelectBy]].
+ * Shortcut for {@link GristView.allowSelectBy}.
  */
 export const allowSelectBy = viewApi.allowSelectBy;
 
 /**
- * Shortcut for [[GristView.setSelectedRows]].
+ * Shortcut for {@link GristView.setSelectedRows}.
  */
 export const setSelectedRows = viewApi.setSelectedRows;
 
@@ -114,7 +114,8 @@ export const setCursorPos = viewApi.setCursorPos;
 
 
 /**
- * Same as [[GristView.fetchSelectedTable]], but the option `keepEncoded` is `false` by default.
+ * Same as {@link GristView.fetchSelectedTable | GristView.fetchSelectedTable},
+ * but the option `keepEncoded` is `false` by default.
  */
 export async function fetchSelectedTable(options: FetchSelectedOptions = {}) {
   options = {...options, keepEncoded: options.keepEncoded || false};
@@ -122,7 +123,8 @@ export async function fetchSelectedTable(options: FetchSelectedOptions = {}) {
 }
 
 /**
- * Same as [[GristView.fetchSelectedRecord]], but the option `keepEncoded` is `false` by default.
+ * Same as {@link GristView.fetchSelectedRecord | GristView.fetchSelectedRecord},
+ * but the option `keepEncoded` is `false` by default.
  */
 export async function fetchSelectedRecord(rowId: number, options: FetchSelectedOptions = {}) {
   options = {...options, keepEncoded: options.keepEncoded || false};
@@ -147,27 +149,27 @@ export const on = rpc.on.bind(rpc);
 // Exposing widgetApi methods in a module scope.
 
 /**
- * Shortcut for [[WidgetAPI.getOption]]
+ * Shortcut for {@link WidgetAPI.getOption}
  */
 export const getOption = widgetApi.getOption.bind(widgetApi);
 
 /**
- * Shortcut for [[WidgetAPI.setOption]]
+ * Shortcut for {@link WidgetAPI.setOption}
  */
 export const setOption = widgetApi.setOption.bind(widgetApi);
 
 /**
- * Shortcut for [[WidgetAPI.setOptions]]
+ * Shortcut for {@link WidgetAPI.setOptions}
  */
 export const setOptions = widgetApi.setOptions.bind(widgetApi);
 
 /**
- * Shortcut for [[WidgetAPI.getOptions]]
+ * Shortcut for {@link WidgetAPI.getOptions}
  */
 export const getOptions = widgetApi.getOptions.bind(widgetApi);
 
 /**
- * Shortcut for [[WidgetAPI.clearOptions]]
+ * Shortcut for {@link WidgetAPI.clearOptions}
  */
 export const clearOptions = widgetApi.clearOptions.bind(widgetApi);