fix: improve some documentation summaries and examples (#22)

* fix: improve some documentation

Also fixed some spelling errors

* Prettier

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.

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.

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<VisSettings>();
- *     return (<div className={`theme-${theme}`}>...</div>);
- *   };
+ *   ```tsx
+ *     type VisSettings = { theme: "dark" | "light" };
+ *
+ *     export default function Visualization() {
+ *       const settings = useSettingsData<VisSettings>();
+ *
+ *       if (!settings) {
+ *         return <div>Did not receive data yet!</div>;
+ *       }
+ *
+ *       return (<div className={`theme-${settings.theme}`}>...</div>);
+ *     }
+ *   ```
  *
  * @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 extends Settings>(): 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<VisSettings>({ theme: "dark" });
- *     return (<>
- *       <label htmlFor="theme">Dark theme:</label>
- *       <input
- *         id="theme"
- *         type="checkbox"
- *         value={config.theme === "dark"}
- *         onChange={e => updateConfig({ theme: e.target.value ? "dark" : "light" })} />
- *     </>);
- *   };
+ *   ```tsx
+ *     type VisSettings = { theme: "dark" | "light" };
+ *
+ *     export default function Settings() {
+ *       const [config, updateConfig] = useSettings<VisSettings>({
+ *         theme: "dark"
+ *       });
+ *
+ *       return (<>
+ *         <label htmlFor="theme">Dark theme:</label>
+ *         <input
+ *           id="theme"
+ *           type="checkbox"
+ *           value={config.theme === "dark"}
+ *           onChange={e => 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<T extends Settings>(
 }
 
 /**
- * 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<T extends Settings>(
 export type UpdateFunction<T> = (changes: Partial<T>) => 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

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";