code documentation

Author: rajrsingh

services/README.md

@@ -1,15 +1,20 @@
+/// REST services for managing the coffee business
 Class ICO.Handler Extends %CSP.REST
 {
-
+/// Honor the CORS header <a href="https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GREST_CORS">as described here</a>
 Parameter HandleCorsRequest = 1;
-
+/// Default response content type
 Parameter CONTENTTYPE = "application/json";
-
+/// Number of days since roasting for the coffee to be considered "stale"
 Parameter MAXAGE = 5;
 
+/// Removes bags of coffee from the catalog
+/// Input: <ul><li>id: catalog ID in catalog</li><li>quantity: number of bags to remove</li></ul>
+/// Output: New product quantity on-hand, or an error
 ClassMethod SellProduct(id As %String, quantity As %Numeric) As %Status
 {
     try {
+        // does the ID exist?
         if (1 '= ##class(ICO.catalog).%ExistsId(id))
         {
             set err = {}
@@ -18,6 +23,7 @@ ClassMethod SellProduct(id As %String, quantity As %Numeric) As %Status
         }
         else 
         {
+            // do we have enough quantity?
             set item = ##class(ICO.catalog).%OpenId(id)
             if (quantity > item.quantity)
             {
@@ -27,33 +33,43 @@ ClassMethod SellProduct(id As %String, quantity As %Numeric) As %Status
             }
             else 
             {
+                // decrement the database and return the new quantity
                 set item.quantity = (item.quantity - quantity)
                 do item.%JSONExportToString(.outstring)
                 write outstring
                 set sc = item.%Save()
             }
         }
     } catch (oException) {
+        // return the error
         set expobj = {}
         set expobj."exception" = oException.%AsSystemError()
         write expobj.%ToJSON()
     }
     Quit $$$OK
 }
 
+/// Gets  bagged coffee inventory for sale from the catalog
+/// Input: fresh: if <pre>1</pre>, return stale bags (roasted more than <PARAMETER>MAXAGE</PARAMETER> days ago).
+/// Output: JSON listing of products
 ClassMethod GetProducts(fresh As %Boolean = 1) As %Status
 {
     try {
+        // fields to return
         set sqlquery = "SELECT catalog_id, product_code, quantity, price, time_roasted, roasting_notes, img FROM ICO.catalog"
+        // set the WHERE clause based on whether we want fresh or not (the -? will be replaced by MAXAGE)
         if fresh = 1 {
             set sqlquery = sqlquery_" WHERE time_roasted > DATEADD('day',-?,CURRENT_DATE)"
         } else {
             set sqlquery = sqlquery_" WHERE time_roasted <= DATEADD('day',-?,CURRENT_DATE)"
         }
+        // if nothing is left, exclude from the response
         set sqlquery = sqlquery_" AND quantity > 0"
+        // run the query
         set rs = ##class(%SQL.Statement).%ExecDirect(,sqlquery, ..#MAXAGE)
         set itemsarray = []
 
+        // iterate over the results and build a dynamic array
         while rs.%Next()
         {
             do itemsarray.%Push(
@@ -68,6 +84,7 @@ ClassMethod GetProducts(fresh As %Boolean = 1) As %Status
                 }
             )
         }
+        // translate the dynamic arry into JSON and return to client
         set itemsobj = {}
         set itemsobj."rowcount" = rs.%ROWCOUNT
         set itemsobj."products" = itemsarray
@@ -80,6 +97,7 @@ ClassMethod GetProducts(fresh As %Boolean = 1) As %Status
     Quit $$$OK
 }
 
+/// Create JSON from POST content
 ClassMethod GetJSONFromRequest(Output obj As %DynamicObject) As %Boolean
 {
     set ok = 1
@@ -91,15 +109,20 @@ ClassMethod GetJSONFromRequest(Output obj As %DynamicObject) As %Boolean
     Quit ok
 }
 
+/// Accepts JSON in an HTTP POST and persists it into the bagged coffee catalog
+/// Input: None explicit. Will get HTTP POST content when calling <METHOD>GetJSONFromRequest</METHOD>
+/// Output: on success, JSON having a key/value of "success": 1, and the object saved, or an error.
 ClassMethod CatalogProduct() As %Status
 {
+    // get HTTP POST content
     if '..GetJSONFromRequest(.obj) {
         set %response.Status = ..#HTTP400BADREQUEST
         set error = {"error": "No JSON body in request"}
         write error.%ToJSON()
         Quit $$$OK
     }
 
+    /// construct a new ICO.catalog object and populate it from the input
     try {
         set catobj = ##class(ICO.catalog).%New()
         set catobj.productcode = obj."product_code"
@@ -121,9 +144,13 @@ ClassMethod CatalogProduct() As %Status
     Quit $$$OK
 }
 
+/// Takes raw coffee beans out of inventory so they can be virtually roasted
+/// Input: <ul><li>id: vendor id in catalog</li><li>quantity: amount in kilograms</li></ul>
+/// Output: on success, JSON of the item and quantity withdrawn, or an error.
 ClassMethod GetRawBeans(id As %String, quantity As %Numeric) As %Status
 {
     try {
+        // does the vendor ID exist?
         if (1 '= ##class(ICO.inventory).%ExistsId(id))
         {
             set err = {}
@@ -132,6 +159,7 @@ ClassMethod GetRawBeans(id As %String, quantity As %Numeric) As %Status
         }
         else 
         {
+            // do we have enough quantity?
             set item = ##class(ICO.inventory).%OpenId(id)
             if (quantity > item.quantitykg)
             {
@@ -141,6 +169,7 @@ ClassMethod GetRawBeans(id As %String, quantity As %Numeric) As %Status
             }
             else 
             {
+                // decrement the quantity and return the requested inventory
                 set item.quantitykg = (item.quantitykg - quantity)
                 set sc = item.%Save()
                 do item.%JSONExportToString(.outstring)
@@ -155,6 +184,9 @@ ClassMethod GetRawBeans(id As %String, quantity As %Numeric) As %Status
     Quit $$$OK
 }
 
+/// Return raw coffee bean inventory
+/// Input: None
+/// Output: on success, JSON listing all products on hand, or an error.
 ClassMethod ListRawBeans() As %Status
 {
     try {

services/cls_Sample/ICO/Handler.cls

@@ -1,19 +1,19 @@
-/// 
+/// Database representation of bagged and roasted coffee
 Class ICO.catalog Extends (%Persistent, %JSON.Adaptor) [ ClassType = persistent, DdlAllowed, Final, Owner = {_SYSTEM}, ProcedureBlock, SqlRowIdPrivate, SqlTableName = catalog ]
 {
-
+/// Unique ID
 Property catalogid As %Library.BigInt(%JSONFIELDNAME = "catalog_id", MINVAL = 1) [ Identity, SqlColumnNumber = 2, SqlFieldName = catalog_id ];
-
+/// Product Code
 Property productcode As %Library.String(%JSONFIELDNAME = "product_code", MAXLEN = 128) [ SqlColumnNumber = 3, SqlFieldName = product_code ];
-
+/// Quantity in number of bags
 Property quantity As %Library.Integer(MAXVAL = 2147483647, MINVAL = -2147483648) [ SqlColumnNumber = 4 ];
-
+/// Price per bag in USD
 Property price As %Library.Numeric(MAXVAL = 99999999.99, MINVAL = -99999999.99, SCALE = 2) [ SqlColumnNumber = 5 ];
-
+/// Time at which the coffee beans were roasted
 Property timeroasted As %Library.DateTime(%JSONFIELDNAME = "time_roasted") [ SqlColumnNumber = 6, SqlFieldName = time_roasted ];
-
+/// Flowery prose describing the taste of the coffee
 Property roastingnotes As %Library.String(%JSONFIELDNAME = "roasting_notes", MAXLEN = 2048) [ SqlColumnNumber = 7, SqlFieldName = roasting_notes ];
-
+/// A product picture
 Property img As %Library.String(MAXLEN = 2048) [ SqlColumnNumber = 8 ];
 
 Parameter USEEXTENTSET = 1;

services/cls_Sample/ICO/catalog.cls

@@ -1,15 +1,15 @@
-/// in step 2 add json.adaptor and jsonfieldname properties
+/// Database representation of raw coffee bean inventory
 Class ICO.inventory Extends (%Persistent, %JSON.Adaptor) [ ClassType = persistent, DdlAllowed, Final, Owner = {_SYSTEM}, ProcedureBlock, SqlRowIdPrivate, SqlTableName = inventory ]
 {
-
+/// Vendor's unique ID
 Property vendorid As %Library.String(%JSONFIELDNAME = "vendor_id", MAXLEN = 128) [ SqlColumnNumber = 2, SqlFieldName = vendor_id ];
-
+/// Vendor's product code
 Property vendorproductcode As %Library.String(%JSONFIELDNAME = "vendor_product_code", MAXLEN = 128) [ SqlColumnNumber = 3, SqlFieldName = vendor_product_code ];
-
+/// Quantity of beans in kilograms
 Property quantitykg As %Library.Numeric(%JSONFIELDNAME = "quantity_kg", MAXVAL = 99999999.99, MINVAL = -99999999.99, SCALE = 2) [ SqlColumnNumber = 4, SqlFieldName = quantity_kg ];
-
+/// Date the product arrived at the warehouse
 Property datearrival As %Library.Date(%JSONFIELDNAME = "date_arrival") [ SqlColumnNumber = 5, SqlFieldName = date_arrival ];
-
+/// Date the product left the producer
 Property datedeparture As %Library.Date(%JSONFIELDNAME = "date_departure") [ SqlColumnNumber = 6, SqlFieldName = date_departure ];
 
 Parameter USEEXTENTSET = 1;

services/cls_Sample/ICO/inventory.cls

@@ -1,5 +1,7 @@
 #!/bin/sh
 
+# Creates JSON files representing bags of roasted coffee coming out of the roastery and ready for import into the sales database, ICO.catalog, using loadproducts.sh
+
 freshdate=$(date +"%Y-%m-%d")
 staledate=$(date -d "-6 days" +"%Y-%m-%d")
 

services/samples/createproducts.sh

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Reads JSON files representing bags of roasted coffee coming out of the roastery and uses a REST API to load the data into the sales catalog
+
+
 IRISDB="http://localhost:52773"
 
 for jsonfile in *.json ;

services/samples/loadproducts.sh

@@ -5,12 +5,12 @@
 KEYFIELDNAMES = ["vendor_id", "vendor_product_code", "quantity_kg"]
 
 def load_manifest(json_data: dict, conn: pyodbc.Connection) -> Exception:
-    """ Use SQL to load records into the data structure
+    """ Use SQL INSERT statements to load records into existing relational tables
     Args:
         json_data: manifest in a Python dictionary
         conn: database connection object
     Returns:
-        true if creation is successful, otherwise returns the exception
+        None if creation is successful, otherwise returns the exception
     """
     cursor = conn.cursor()
     fieldnamesql = "INSERT INTO ICO.inventory (vendor_id, vendor_product_code, quantity_kg, date_arrival)"
@@ -35,6 +35,12 @@ def load_manifest(json_data: dict, conn: pyodbc.Connection) -> Exception:
 
 
 def validate_manifest(json_data: dict) -> tuple:
+    """ Verify that the manifest file contains valid inventory data
+    Args:
+        json_data: manifest in a Python dictionary
+    Returns:
+        a tuple (original JSON data, True, None) if valid, (None, false, exception) if not
+    """
     try:
         # check if items exists
         if (json_data.get("items")) is None:
@@ -79,6 +85,12 @@ def get_connection_info(file_name):
     return connections
 
 def main():
+    """ Entry point to running the program. Loads a file in the same directory named order_manifest.json, parses the file into SQL INSERT statements, and loads the inventory into the database
+    Args:
+        None
+    Returns:
+        Nothing
+    """
     with open('./order_manifest.json') as f:
         data = json.load(f)