docs: add missing types, errors and refine docstrings for ShoppingCart and ProductCatalog

Author: tmlmt

src/classes/product_catalog.ts

@@ -13,9 +13,7 @@ import {
 import { InvalidProductCatalogFormat } from "../errors";
 
 /**
- * Product Catalog Manager
- *
- * Used in conjunction with {@link ShoppingCart}
+ * Product Catalog Manager: used in conjunction with {@link ShoppingCart}
  *
  * ## Usage
  *
@@ -28,10 +26,12 @@ import { InvalidProductCatalogFormat } from "../errors";
  * ```typescript
  * import { ProductCatalog } from "@tmlmt/cooklang-parser";
  *
- * const catalog = `[eggs]
+ * const catalog = `
+ * [eggs]
  * aliases = ["oeuf", "huevo"]
  * 01123 = { name = "Single Egg", size = "1", price = 2 }
  * 11244 = { name = "Pack of 6 eggs", size = "6", price = 10 }
+ *
  * [flour]
  * aliases = ["farine", "Mehl"]
  * 01124 = { name = "Small pack", size = "100%g", price = 1.5 }

src/classes/shopping_cart.ts

@@ -53,7 +53,7 @@ export interface ShoppingCartSummary {
 }
 
 /**
- * Shopping Cart Manager: a tool to find the best combination of products to buy to satisfy a shopping list.
+ * Shopping Cart Manager: a tool to find the best combination of products to buy (defined in a {@link ProductCatalog}) to satisfy a {@link ShoppingList}.
  *
  * @example
  * ```ts

src/errors.ts

@@ -14,6 +14,10 @@ You can either remove the reference to create a new ${item_type} defined as ${ne
   }
 }
 
+/**
+ * Error thrown when trying to build a shopping cart without a product catalog
+ * @category Errors
+ */
 export class NoProductCatalogForCartError extends Error {
   constructor() {
     super(
@@ -23,6 +27,10 @@ export class NoProductCatalogForCartError extends Error {
   }
 }
 
+/**
+ * Error thrown when trying to build a shopping cart without a shopping list
+ * @category Errors
+ */
 export class NoShoppingListForCartError extends Error {
   constructor() {
     super(

src/index.ts

@@ -9,6 +9,15 @@ import {
 } from "./classes/shopping_cart";
 import { Section } from "./classes/section";
 
+export {
+  CategoryConfig,
+  ProductCatalog,
+  Recipe,
+  ShoppingList,
+  ShoppingCart,
+  Section,
+};
+
 import type {
   Metadata,
   Ingredient,
@@ -19,6 +28,7 @@ import type {
   DecimalValue,
   FractionValue,
   TextValue,
+  FixedNumericValue,
   Timer,
   TextItem,
   IngredientItem,
@@ -47,13 +57,8 @@ import type {
 } from "./types";
 
 export {
-  Recipe,
-  ShoppingList,
-  ShoppingCart,
   ShoppingCartOptions,
   ShoppingCartSummary,
-  CategoryConfig,
-  ProductCatalog,
   Metadata,
   Ingredient,
   IngredientFlag,
@@ -63,6 +68,7 @@ export {
   DecimalValue,
   FractionValue,
   TextValue,
+  FixedNumericValue,
   Timer,
   TextItem,
   IngredientItem,
@@ -79,7 +85,6 @@ export {
   RecipeWithServings,
   CategoryIngredient,
   Category,
-  Section,
   QuantityPart,
   ProductOption,
   ProductSelection,
@@ -90,3 +95,10 @@ export {
   CartMisMatch,
   NoProductMatchErrorCode,
 };
+
+import {
+  NoProductCatalogForCartError,
+  NoShoppingListForCartError,
+} from "./errors";
+
+export { NoProductCatalogForCartError, NoShoppingListForCartError };

src/types.ts

@@ -170,6 +170,11 @@ export interface FixedValue {
   value: TextValue | DecimalValue | FractionValue;
 }
 
+/**
+ * Represents a single, fixed numeric quantity.
+ * This can be a decimal or fraction.
+ * @category Types
+ */
 export interface FixedNumericValue {
   type: "fixed";
   value: DecimalValue | FractionValue;
@@ -495,6 +500,10 @@ export interface ProductMatch {
  */
 export type CartMatch = ProductMatch[];
 
+/**
+ * Represents the error codes for an ingredient which didn't match with any product in the product catalog, in a {@link ShoppingCart}
+ * @category Types
+ */
 export type NoProductMatchErrorCode =
   | "incompatibleUnits"
   | "noProduct"