doc(lib) Make documentation easier to read, to facilitate use of the …

…various functions and their configuration

.gitignore

@@ -2,3 +2,4 @@
 /dist
 ods-charts*.tgz
 /docs/api
+/test_local

README.md

@@ -73,6 +73,8 @@ myChart.setOption(themeManager.getChartOptions(dataOptions));
 
 The `themeManager` returned by `getThemeManager()` can be used to add other features supported by the ODS Charts library.
 
+Read the [API documentaion](https://ods-charts.netlify.app/api/) for details on this legends, popover, tooltip... features.
+
 Read the [documentation](https://ods-charts.netlify.app/) for information on the library content and examples.
 
 ## Status

docs/README.md

@@ -19,6 +19,30 @@ Once the library integrated, via
 
 use `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) to get the {@link ODSChartsTheme}.
 
+The ODS Charts library is configured
+
+- by settings options on {@link ODSChartsThemeOptions}
+- by calling features on {@link ODSChartsTheme}
+
+{@link ODSChartsTheme.getThemeManager}
+
+### Theme options
+
+The theme is configured with {@link ODSChartsThemeOptions}:
+
+- {@link ODSChartsThemeOptions.categoricalColors}: colors to be used to graph the chart.
+- {@link ODSChartsThemeOptions.cssTheme}: optionaly indicates a external theme to be used like boosted.
+- {@link ODSChartsThemeOptions.lineStyle}: style of line in lineCharts.
+- {@link ODSChartsThemeOptions.mode}: fixes the light or dark mode.
+
+### Graph features
+
+And additional features can be added calling methods on {@link ODSChartsTheme}:
+
+- {@link ODSChartsTheme.externalizeLegends}: to add Orange Design System theme to legends.
+- {@link ODSChartsTheme.externalizePopover}: to add Orange Design System theme to popover or tooltip.
+- {@link ODSChartsTheme.manageChartResize}`: to dynamically adapt graph size the its container.
+
 The {@link ODSChartsTheme} is used to build the ODS theme and the charts options.
 
 ## Examples

package.json

@@ -23,7 +23,7 @@
     "serve:any": "serve",
     "serve:react": "serve test/react/build/",
     "serve:vue": "serve test/vue/dist/",
-    "typedoc": "typedoc --out docs/api src/ods-charts.ts --disableSources --excludePrivate --excludeProtected --readme docs/README.md && node build/add_head.mjs",
+    "typedoc": "typedoc --out docs/api src/ods-charts.ts --skipErrorChecking --disableSources --excludePrivate --excludeProtected --readme docs/README.md && node build/add_head.mjs",
     "watch": "webpack --watch --mode development"
   },
   "devDependencies": {

src/ods-charts.ts

@@ -9,13 +9,9 @@
 /**
  * @packageDocumentation
  *
- * Once the library integrated, via
- * - script <script src="...ods-charts.js">
- * - or an import * as ODSCharts from 'ods-charts'
+ * This page is an index of the module's classes, interfaces and enumeration.
  *
- * use `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) to get the {@link ODSChartsTheme}.
- *
- * The {@link ODSChartsTheme} is used to build the ODS theme and the charts options.
+ * Their use is introduced on the [home page](./#md:documentation).
  *
  */
 import { ODSChartsTheme } from './theme/ods-chart-theme';

src/theme/legends/ods-chart-legends-definitions.ts

@@ -7,7 +7,7 @@
 //
 
 /**
- * Definition of a container used to display legends.
+ * Definition of a container used to display legends, refer to {@link ODSChartsTheme.externalizeLegends}.
  *
  * Example of use:
  * ```

src/theme/ods-chart-theme.ts

@@ -141,6 +141,9 @@ export enum ODSChartsMode {
   DARK = 'dark',
 }
 
+/**
+ * `ODSChartsThemeOptions` is used to set options of the theme [ODSCharts.getThemeManager( ODSChartsThemeOptions)](../#md:documentation).
+ */
 export interface ODSChartsThemeOptions {
   /**
    * The mode of the theme can be {@link ODSChartsMode.LIGHT} or  {@link ODSChartsMode.DARK}.
@@ -276,7 +279,7 @@ const THEMES: {
 };
 
 /**
- * ODSChartsTheme is the object get by `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions})
+ * ODSChartsTheme is the object get by `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}), refer to {@link ODSChartsTheme.getThemeManager}
  *
  * This manager is used to
  * - get the ODS theme, register it, and use it
@@ -292,13 +295,16 @@ const THEMES: {
  * themeManager.setDataOptions(<dataOptions>);
  * // Register the externalization of the legend.
  * themeManager.externalizeLegends(...);
- * // Manage window size changed
+ * // Manage chart container size changed
  * themeManager.manageChartResize(...);
  * // Register the externalization of the tooltip/popup
  * themeManager.externalizePopover(...);
  * // Display the chart using the configured theme and data.
  * myChart.setOption(themeManager.getChartOptions());
  * ```
+ *
+ * See {@link ODSChartsTheme.getThemeManager} for details.
+ *
  */
 export class ODSChartsTheme {
   private dataOptions: any;
@@ -319,13 +325,27 @@ export class ODSChartsTheme {
   }
 
   /**
-   * Entry point of the library. It returns the generated theme manager.
+   * Entry point of the library.
    *
-   * This manager is used to retrieve the Apache ECharts theme and manage the chart options in accordance with the Orange Design System.
+   * Once the library integrated, via
+   * - script &lt;script src="...ods-charts.js"&gt;
+   * - or an import \* as ODSCharts from 'ods-charts'
+   *
+   * use `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) to get the {@link ODSChartsTheme}.
+   *
+   * It returns the generated theme manager.
    *
-   * The method takes the theme configuration as a parameter {@link ODSChartsThemeOptions}.
-   * @param options default option used to generate the theme
-   * @returns the theme manager
+   * @param options options used to generate the theme.
+   * - {@link ODSChartsThemeOptions.categoricalColors}: colors to be used to graph the chart.
+   * - {@link ODSChartsThemeOptions.cssTheme}: optionaly indicates a external theme to be used like boosted.
+   * - {@link ODSChartsThemeOptions.lineStyle}: style of line in lineCharts.
+   * - {@link ODSChartsThemeOptions.mode}: fixes the light or dark mode.
+   * @returns the theme manager.
+   * This manager is used to retrieve the Apache ECharts theme and manage the chart options in accordance with the Orange Design System.
+   * It is used to add features:
+   * - {@link ODSChartsTheme.externalizeLegends}: to add Orange Design System theme to legends.
+   * - {@link ODSChartsTheme.externalizePopover}: to add Orange Design System theme to popover or tooltip.
+   * - {@link ODSChartsTheme.manageChartResize}`: to dynamically adapt graph size the its container.
    */
   public static getThemeManager(options?: ODSChartsThemeOptions): ODSChartsTheme {
     if (!options) {
@@ -378,7 +398,7 @@ export class ODSChartsTheme {
   }
 
   /**
-   * setDataOptions is used to set the graph data.
+   * Set the original [Apache Echarts data options](https://echarts.apache.org/en/option.html) of your graph.
    *
    * Example:
    * ```
@@ -396,8 +416,8 @@ export class ODSChartsTheme {
    *         ],
    *       })
    * ```
-   * @param options
-   * @returns returns back the theme manager object
+   * @param options the [Apache Echarts data options](https://echarts.apache.org/en/option.html) of your graph.
+   * @returns the theme manager object
    */
   public setDataOptions(options: any): ODSChartsTheme {
     this.dataOptions = options;
@@ -427,7 +447,9 @@ export class ODSChartsTheme {
    * getThemeOptions() does not need to be called if you use getChartOptions() as getChartOptions() internally already calls it.
    *
    * getThemeOptions() needs graph data, already set or given in the dataOptions parameter
-   * @returns  returns back the theme manager object
+   *
+   * @param dataOptions optionally you can use this call to set dataOptions, if not already set.
+   * @returns modifications to be made to the [Apache Echarts data options](https://echarts.apache.org/en/option.html) to implement the Orange Design System.
    */
   public getThemeOptions(dataOptions?: any): any {
     if (dataOptions) {
@@ -529,12 +551,14 @@ export class ODSChartsTheme {
    * - will implement the Orange Design System
    * - will be link with the graph.
    *
-   * externalizeLegends() needs:
-   * - echart: the initialized eCharts object
-   * - legendHolderSelector: the CSS selector of the legends container if it a string. But it can also be a {@link ODSChartsLegendHolderDefinition} or an array of {@link ODSChartsLegendHolderDefinition}
-   *
-   * optionally you can use this call to set dataOptions
-   * @returns returns back the theme manager object
+   * @param echart the initialized eCharts object
+   * @param legendHolderSelector
+   * legendHolderSelectorcan be
+   * - a string, and then is interprated as the CSS selector of the legends container
+   * - a {@link ODSChartsLegendHolderDefinition} if you want to sepcify the orientation of the legends holder or specify the series to be displayed in the legends holder
+   * - an array of {@link ODSChartsLegendHolderDefinition} if you want to group legends in several legends holders
+   * @param dataOptions optionally you can use this call to set dataOptions, if not already set.
+   * @returns the theme manager object itself to be able to chain calls.
    */
   public externalizeLegends(
     echart: any,
@@ -553,16 +577,12 @@ export class ODSChartsTheme {
    *
    * The generated tooltips or popover will implement the Orange Design System.
    *
-   * externalizePopover() needs:
-   * - popoverConfig: the configuration of the externalizePopover feature {@link ODSChartsPopoverConfig}
-   * - popoverDefinition: a renderer {@link ODSChartsPopoverDefinition} of the popover/tooltip
-   *
-   *   {@link ODSChartsPopoverManagers} gives preconfigured renderer
-   *
-   *   default value is  {@link ODSChartsPopoverManagers.NONE}: uses default Apache ECharts template to externalize tooltip/popover HTML element, implementing Orange Design system
-   *
-   * optionally you can use this call to set dataOptions
-   * @returns returns back the theme manager object
+   * @param popoverConfig the configuration of the externalizePopover feature {@link ODSChartsPopoverConfig}
+   * @param popoverDefinition renderer {@link ODSChartsPopoverDefinition} of the popover/tooltip. **{@link ODSChartsPopoverManagers}** is used to
+   * specify preconfigured renderer for Apache ECharts, Boosted 5 or Boosted 4 renderer.
+   * default value is  {@link ODSChartsPopoverManagers.NONE}, that means it uses default Apache ECharts template to externalize tooltip/popover HTML element, implementing Orange Design system
+   * @param dataOptions optionally you can use this call to set dataOptions, if not already set.
+   * @returns the theme manager object itself to be able to chain calls.
    */
   public externalizePopover(popoverConfig: ODSChartsPopoverConfig = {}, popoverDefinition?: ODSChartsPopoverDefinition, dataOptions?: any): ODSChartsTheme {
     if (dataOptions) {
@@ -576,14 +596,12 @@ export class ODSChartsTheme {
   }
 
   /**
-   * manageChartResize() ensures that the graph resizes correctly when the window is resized
-   *
-   * manageChartResize() needs:
-   * - echart: the initialized eCharts object
-   * - chartId: an unique id to identify the chart
+   * manageChartResize() ensures that the graph resizes correctly when its container is resized
    *
-   * optionally you can use this call to set dataOptions
-   * @returns returns back the theme manager object
+   * @param echart the initialized eCharts object.
+   * @param chartId an unique id that identify the chart container in the DOM.
+   * @param dataOptions optionally you can use this call to set dataOptions, if not already set.
+   * @returns the theme manager object itself to be able to chain calls.
    */
   public manageChartResize(echart: any, chartId: string, dataOptions?: any): ODSChartsTheme {
     if (dataOptions) {
@@ -595,14 +613,14 @@ export class ODSChartsTheme {
 
   /**
    * getChartOptions() build the eCharts options merging
-   * - options implementing the Orange Design System
+   * - options implementing the Orange Design System {@link ODSChartsThemeOptions}
    * - optionally options implementing {@link externalizeLegends},
    * - optionally options implementing {@link externalizePopover},
    * - optionally options implementing {@link manageChartResize},
    * - data from {@link setDataOptions}
    *
-   * optionally you can use this call to set dataOptions
-   * @returns the Apache ECharts options
+   * @param dataOptions optionally you can use this call to set dataOptions, if not already set.
+   * @returns the Apache ECharts options to use in [Apache Echarts setOption()](https://echarts.apache.org/en/option.html) call.
    */
   public getChartOptions(dataOptions?: any): any {
     if (dataOptions) {

src/theme/popover/ods-chart-popover-definitions.ts

@@ -40,10 +40,11 @@ export class ODSChartsPopoverItem {
 
 /**
  * {@link ODSChartsPopoverDefinition} defines the interface of the manager of externalized
- * popover or tooltip.
+ * popover or tooltip {@link ODSChartsTheme.externalizePopover}.
  *
+ * {@link ODSChartsPopoverDefinition} is not used directly. Instead, we use the variable **{@link ODSChartsPopoverDefinition}.
  * {@link ODSChartsPopoverManagers} gives 3 default {@link ODSChartsPopoverDefinition}
- * managers.
+ * managers for Apache ECharts, Boosted 5 and Boosted 4.
  *
  * You probably need to use one of those.
  *
@@ -138,7 +139,7 @@ export enum ODSChartsPopoverTooltipTrigger {
 }
 
 /**
- * Configuration of the externalizePopover feature.
+ * Configuration of the externalizePopover feature {@link ODSChartsTheme.externalizePopover}.
  *
  */
 export class ODSChartsPopoverConfig {
@@ -303,10 +304,12 @@ class BOOSTED4_Definition extends ODSChartsPopoverDefinitionWithRenderer {
 }
 
 /**
+ * `ODSChartsPopoverManagers` is used to specify popoverDefinition parameter (popup/tooltip renderer) of {@link ODSChartsTheme.externalizePopover}.
+ *
  * Available popover/tooltip renderer:
- * - ODSChartsPopoverManagers.NONE: to use default ECharts template to externalize tooltip/popover HTML element, implementing Orange Design System
- * - ODSChartsPopoverManagers.BOOSTED5: to use Boosted 5 tooltip/popover
- * - ODSChartsPopoverManagers.BOOSTED4: to use Boosted 4 tooltip/popover
+ * - `ODSChartsPopoverManagers.NONE`: to use default ECharts template to externalize tooltip/popover HTML element, implementing Orange Design System
+ * - `ODSChartsPopoverManagers.BOOSTED5`: to use Boosted 5 tooltip/popover
+ * - `ODSChartsPopoverManagers.BOOSTED4`: to use Boosted 4 tooltip/popover
  */
 export const ODSChartsPopoverManagers: {
   [name in ODSChartsCSSThemesNames]?: ODSChartsPopoverDefinition;