(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
4 months ago · 8ddcff4310
parent eee29ee0a0
commit 8ddcff4310
3 changed files with 42 additions and 65 deletions
--- a/app/plugin/GristAPI.ts
+++ b/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]]
- * - [[onRecord]]
- * - [[fetchSelectedRecord]]
- * - [[fetchSelectedTable]]
- * - [[GristView.fetchSelectedRecord]]
- * - [[GristView.fetchSelectedTable]]
+ * - {@link onRecords}
+ * - {@link onRecord}
+ * - {@link fetchSelectedRecord}
+ * - {@link fetchSelectedTable}
+ * - {@link GristView.fetchSelectedRecord | GristView.fetchSelectedRecord}
+ * - {@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>;
--- a/app/plugin/GristData.ts
+++ b/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    | LookUp         |
- * | O    | Dict           |
- * | D    | DateTime       |
- * | d    | Date           |
- * | C    | Censored       |
- * | R    | Reference      |
- * | r    | ReferenceList  |
- * | E    | Exception      |
- * | P    | Pending        |
- * | U    | Unmarshallable |
- * | V    | Version        |
+ * | `L`  | List, e.g. `["L", "foo", "bar"]` or `["L", 1, 2]` |
+ * | `l`  | LookUp, as `["l", value, options]` |
+ * | `O`  | Dict, as `["O", {key: value, ...}]` |
+ * | `D`  | DateTimes, as `["D", timestamp, timezone]`, e.g. `["D", 1704945919, "UTC"]` |
+ * | `d`  | Date, as `["d", timestamp]`, e.g. `["d", 1704844800]` |
+ * | `C`  | Censored, as `["C"]` |
+ * | `R`  | Reference, as `["R", table_id, row_id]`, e.g. `["R", "People", 17]` |
+ * | `r`  | ReferenceList, as `["r", table_id, row_id_list]`, e.g. `["r", "People", [1,2]]` |
+ * | `E`  | Exception, as `["E", name, ...]`, e.g. `["E", "ValueError"]` |
+ * | `P`  | Pending, as `["P"]` |
+ * | `U`  | Unmarshallable, as `["U", text_representation]` |
+ * | `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[];
--- a/app/plugin/grist-plugin-api.ts
+++ b/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);