Archives
/
gristlabs_grist-core
mirror of https://github.com/gristlabs/grist-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Browse Source 
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
pull/825/head
Dmitry S 5 months ago
parent eee29ee0a0
commit 8ddcff4310
3 changed files with 42 additions and 65 deletions
Show Stats Download Patch File Download Diff File

19
app/plugin/GristAPI.ts
Unescape View File

@ -118,7 +118,7 @@ export interface GristDocAPI {
listTables(): Promise<string[]>; 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 * 'id' column. Do not modify the returned arrays in-place, especially if used
* directly (not over RPC). * directly (not over RPC).
*/ */
@ -142,18 +142,18 @@ export interface GristDocAPI {
/** /**
* Options for functions which fetch data from the selected table or record: * 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`. * The different methods have different default values for `keepEncoded` and `format`.
**/ **/
export interface FetchSelectedOptions { 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. * - `false`: the values will be decoded, replacing e.g. `['D', timestamp]` with a moment date.
*/ */
keepEncoded?: boolean; keepEncoded?: boolean;
@ -178,7 +178,8 @@ export interface FetchSelectedOptions {
*/ */
export interface GristView { 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`. * By default, `options.keepEncoded` is `true` and `format` is `columns`.
*/ */
fetchSelectedTable(options?: FetchSelectedOptions): Promise<any>; fetchSelectedTable(options?: FetchSelectedOptions): Promise<any>;

68
app/plugin/GristData.ts
Unescape View File

@ -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 { export enum GristObjCode {
List = 'L', List = 'L',
@ -19,14 +19,6 @@ export enum GristObjCode {
/** /**
* Possible types of cell content. * 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`) * 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 * 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 | * | 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 { export interface RowRecord {
id: number; 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. * 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 { export interface RowRecords {
id: number[]; id: number[];

20
app/plugin/grist-plugin-api.ts
Unescape View File

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

Write Preview
Loading…
Cancel
Save