Add documentation to the config file

Vitalius1 · Vitalius1 · commit c094777411d3 · 2019-06-04T19:22:49.000-07:00
diff --git a/apps/api-documenter/src/documenters/IConfigFile.ts b/apps/api-documenter/src/documenters/IConfigFile.ts
@@ -10,36 +10,42 @@ export interface IConfigTableOfContents {
   /**
    * Represents the tree structure describing the toc.file format.
    * Nodes that have an empty `items` array property or their name will be included in the
-   * {@link IConfigTableOfContents.categoryNodes} will be filled with API items
-   * that are matched with the filters provided. Everything else will be placed under a catchAll category
-   * that is highly recommended to be provided.
+   * {@link IConfigTableOfContents.nonEmptyCategoryNodeNames} will be filled with API items
+   * that are matched with the filters provided. Everything else will be placed under
+   * {@link IConfigTableOfContents.catchAllCategory} if provided, which is highly recommended.
    */
   tocConfig: IYamlTocFile;
 
   /**
    * Optional category name that is recommended to be included along with
-   * one of the filters available: `filterByApiItemName` or `filterByInlineTag`.
-   * Any items that are not matched to the mentioned filters will be placed under this
+   * one of the configs: {@link IConfigTableOfContents.categorizeByName} or
+   * {@link IConfigTableOfContents.categoryInlineTag}.
+   * Any items that are not matched according to the mentioned configuration options will be placed under this
    * catchAll category. If none provided the items will not be included in the final toc.yml file.
    */
   catchAllCategory?: string;
 
   /**
-   * Toggle either sorting of the API items should be made based on category name presence
+   * Toggle either categorization of the API items should be made based on category name presence
    * in the API item's name. Useful when there are API items without an inline tag to categorize them,
-   * but still need to filter the items under categories. Note: this type of filter might place some items
-   * under wrong categories if the names similar but are supposed to be in different categories.
+   * but still need to place the items under categories. Note: this type of categorization might place some items
+   * under wrong categories if the names are similar but belong to different categories.
+   * In case that {@link IConfigTableOfContents.categoryInlineTag} is provided it will try categorize by
+   * using it and only if it didn't, it will attempt to categorize by name.
    */
   categorizeByName?: boolean;
 
   /**
-   * Filter that can be used to sort the API items according to an inline custom tag
-   * that is present on them.
+   * Inline tag that will be used to categorize the API items. Will take precedence over the
+   * {@link IConfigTableOfContents.categorizeByName} flag in trying to place the API item according to the
+   * custom inline tag present in documentation of the source code.
    */
   categoryInlineTag?: string;
 
   /**
-   * Array of node names to which API items will be pushed when filtered
+   * Array of node names that might have already items injected at the time of creating the
+   * {@link IConfigTableOfContents.tocConfig} tree structure but are still needed to be included as category
+   * nodes where API items will be pushed during the categorization algorithm.
    */
   nonEmptyCategoryNodeNames?: string[];
 }
