mirror of
https://github.com/gristlabs/grist-core.git
synced 2024-10-27 20:44:07 +00:00
(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
This commit is contained in:
Dmitry S
parent
eee29ee0a0
commit
8ddcff4310
@ -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>;
|
||||
|
||||
@ -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[];
|
||||
|
||||
@ -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);
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user