From 64e4483db350b11b64f83692a903b900a6d434d1 Mon Sep 17 00:00:00 2001 From: Tjalle-S <91267211+Tjalle-S@users.noreply.github.com> Date: Mon, 20 May 2024 14:34:55 +0200 Subject: [PATCH] fix: improve some documentation summaries and examples (#22) * fix: improve some documentation Also fixed some spelling errors * Prettier --- src/base/eventListeners.ts | 10 +-- src/base/graphQueryResult.types.ts | 20 +++--- src/react/hooks.ts | 97 +++++++++++++++++++----------- src/react/index.ts | 6 +- 4 files changed, 80 insertions(+), 53 deletions(-) diff --git a/src/base/eventListeners.ts b/src/base/eventListeners.ts index 7359a10..86514f7 100644 --- a/src/base/eventListeners.ts +++ b/src/base/eventListeners.ts @@ -10,7 +10,7 @@ import type { GraphQueryResult, ML, SchemaGraph, Settings } from "."; import type { ReceiveMessage, SendMessage } from "../internal"; /** - * Performs an action everytime a message of the specified type is received. + * Performs an action every time a message of the specified type is received. * * @param typeFilter The type of messages to listen for. * @param callback The action to perform an receiving a message. @@ -43,7 +43,7 @@ export function receiveMessage< } /** - * Performs an action everytime a message with graph data is received. + * Performs an action every time a message with graph data is received. * * @param callback The action to perform an receiving a message. * @@ -56,7 +56,7 @@ export function receiveGraphData(callback: (data: GraphQueryResult) => void) { } /** - * Performs an action everytime a message with settings is received. + * Performs an action every time a message with settings is received. * * @param callback The action to perform an receiving a message. * @@ -69,7 +69,7 @@ export function receiveSettings(callback: (data: Settings) => void) { } /** - * Performs an action everytime a message with a schema graph is received. + * Performs an action every time a message with a schema graph is received. * * @param callback The action to perform an receiving a message. * @@ -82,7 +82,7 @@ export function receiveSchema(callback: (data: SchemaGraph) => void) { } /** - * Performs an action everytime a message with machine learning data is + * Performs an action every time a message with machine learning data is * received. * * @param callback The action to perform an receiving a message. diff --git a/src/base/graphQueryResult.types.ts b/src/base/graphQueryResult.types.ts index 5ea948f..c53cfca 100644 --- a/src/base/graphQueryResult.types.ts +++ b/src/base/graphQueryResult.types.ts @@ -5,7 +5,7 @@ * * @category Graph data */ -export interface GraphQueryResult { +export type GraphQueryResult = { /** * Lists all the edges in the graph. */ @@ -23,14 +23,14 @@ export interface GraphQueryResult { * progress. */ queryingBackend: boolean; -} +}; /** * A single node inside a graph. * * @category Graph data */ -export interface Node { +export type Node = { /** * The ID of the node. Unique within the graph it is contained in. */ @@ -44,14 +44,14 @@ export interface Node { // TODO: document. mldata?: unknown; // FIXME /* type: string[]; */ -} +}; /** * A single edge inside a graph. * * @category Graph data */ -export interface Edge { +export type Edge = { /** * Additional attributes associated with the edge. */ @@ -73,7 +73,7 @@ export interface Edge { */ to: string; /* type: string; */ -} +}; /** * Metadata associated with a graph. @@ -122,7 +122,7 @@ export type CompressedElement = { * * @category Graph data */ -export interface ElementTypeMetadata { +export type ElementTypeMetadata = { /** * Additional attributes associated with the elements. */ @@ -139,14 +139,14 @@ export interface ElementTypeMetadata { * The number of elements with this label. */ count: number; -} +}; /** * Attributes associated with a group of elements. * * @category Graph data */ -export interface ElementTypeAttributes { +export type ElementTypeAttributes = { /** * The type of the attribute. */ @@ -159,7 +159,7 @@ export interface ElementTypeAttributes { * The values of the attribute, associated with this label, if applicable. */ values?: unknown[]; -} +}; /** * The type of an attribute. diff --git a/src/react/hooks.ts b/src/react/hooks.ts index ef29456..8650333 100644 --- a/src/react/hooks.ts +++ b/src/react/hooks.ts @@ -115,10 +115,14 @@ function useMessage< } /** - * Returns the data of the last message containing graph data. that has been - * sent, or `null` if no such message has been sent. + * Returns the current graph data, or `undefined` if they are not (yet) + * available. * - * Component rerenders on receiving a new message. + * @remarks + * Component rerenders when the returned value changes. + * + * @returns A {@link GraphQueryResult} containing the raw data of the current + * graph. * * @category React hooks */ @@ -127,13 +131,18 @@ export function useGraphData(): GraphQueryResult | undefined { } /** - * Returns the data of the last message containing machine learning data that - * has been sent, or `null` if no such message has been sent. + * Returns the current machine learning results, or `undefined` if they are not + * (yet) available. * - * Component rerenders on receiving a new message. + * @remarks + * Component rerenders when the returned value changes. + * + * @returns A {@link ML} containing the results from the active machine learning + * plugins. * * @category React hooks */ +// TODO: don't forget to update the link once the new ML type is merged. export function useMLData(): ML | undefined { return useMessage("MLData"); } @@ -144,22 +153,30 @@ export function useMLData(): ML | undefined { * configuration. * * @remarks - * This hook should only be used for the visualization component. For setting - * components use the {@link useSettings} hook that can also push a new - * configuration to GraphPolaris. + * This hook should only be used for the visualization component. For the + * settings component, use the {@link useSettings} hook that can also push a + * new configuration to GraphPolaris. * * @example - * type VisSettings = { theme: "dark" | "light" }; - * export default function Visualisation() { - * const { theme } = useSettingsData(); - * return (
...
); - * }; + * ```tsx + * type VisSettings = { theme: "dark" | "light" }; + * + * export default function Visualization() { + * const settings = useSettingsData(); + * + * if (!settings) { + * return
Did not receive data yet!
; + * } + * + * return (
...
); + * } + * ``` * * @template T The type of the configuration which must adhere to the * configuration requirements. * - * @returns Returns the last message containing visualization settings that has - * been sent, or `null` if no configuration has yet been sent. + * @returns Returns the currently selected configuration, or `undefined` if it + * is not (yet) available. * * @category React hooks * @category Settings @@ -174,22 +191,31 @@ export function useSettingsData(): T | undefined { * * @remarks * This hook should only be used for the settings component. The update - * function's messages are ignored by GraphPorlaris if it is called from the - * visualisation component, use the {@link useSettingsData} hook instead. + * function's messages are ignored by GraphPolaris if it is called from the + * visualization component. For the visualization component, use the + * {@link useSettingsData} hook instead. * * @example - * type VisSettings = { theme: "dark" | "light" }; - * export default function Settings() { - * const [config, updateConfig] = useSettings({ theme: "dark" }); - * return (<> - * - * updateConfig({ theme: e.target.value ? "dark" : "light" })} /> - * ); - * }; + * ```tsx + * type VisSettings = { theme: "dark" | "light" }; + * + * export default function Settings() { + * const [config, updateConfig] = useSettings({ + * theme: "dark" + * }); + * + * return (<> + * + * updateConfig({ + * theme: e.target.value ? "dark" : "light" + * })}/> + * ); + * } + * ``` * * @template T The type of the configuration which must adhere to the * configuration requirements. @@ -229,7 +255,7 @@ export function useSettings( } /** - * A function to send an update to the visualisation's configuration. + * A function to send an update to the visualization's configuration. * * @see {@link useSettings} * @@ -238,12 +264,13 @@ export function useSettings( export type UpdateFunction = (changes: Partial) => void; /** - * Returns the data of the last message containing the schema graph that has - * been sent, or `null` if no such message has been sent. + * Returns the current schema graph, or `undefined` if it is not (yet) + * available. * - * Component rerenders on receiving a new message. + * @remarks + * Component rerenders when the returned value changes. * - * @returns A `SchemaGraph` containing the schema of the currently selected + * @returns A {@link SchemaGraph} containing the schema of the currently selected * data. * * @category React hooks diff --git a/src/react/index.ts b/src/react/index.ts index 2265a35..a689afa 100644 --- a/src/react/index.ts +++ b/src/react/index.ts @@ -7,12 +7,12 @@ */ /** - * @packageDocumentation Contains React bindings for the GraphPolaris visualisation plugin API. + * @packageDocumentation Contains React bindings for the GraphPolaris visualization plugin API. * * @categoryDescription React hooks - * These functions are designed to work as react hooks, they will cause a rerender if the value that is returned is updated by GraphPolaris. + * These functions are designed to work as react hook. If the returned value that is returned is updated by GraphPolaris, they will trigger a rerender. * @categoryDescription Settings - * All functions and types that are related to building a settings interface for a visualisation. + * All functions and types that are related to building a settings interface for a visualization. */ export * from "./hooks";