From 8ddcff431080b5f061555560c2e230a873ed882f Mon Sep 17 00:00:00 2001 From: Dmitry S Date: Thu, 11 Jan 2024 18:14:24 -0500 Subject: [PATCH] (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 | 19 +++++----- app/plugin/GristData.ts | 68 +++++++++++----------------------- app/plugin/grist-plugin-api.ts | 20 +++++----- 3 files changed, 42 insertions(+), 65 deletions(-) diff --git a/app/plugin/GristAPI.ts b/app/plugin/GristAPI.ts index c5c1fa5c..25e44015 100644 --- a/app/plugin/GristAPI.ts +++ b/app/plugin/GristAPI.ts @@ -118,7 +118,7 @@ export interface GristDocAPI { listTables(): Promise; /** - * 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; diff --git a/app/plugin/GristData.ts b/app/plugin/GristData.ts index 6853cdd2..b56a06a8 100644 --- 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[]; diff --git a/app/plugin/grist-plugin-api.ts b/app/plugin/grist-plugin-api.ts index ce1981a0..28ef43cf 100644 --- a/app/plugin/grist-plugin-api.ts +++ b/app/plugin/grist-plugin-api.ts @@ -98,12 +98,12 @@ export const sectionApi = rpc.getStub('CustomSectionAPI', chec export const commandApi = rpc.getStub('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);