docs: improving documentation

raul-casallas · raul-casallas · commit dab3b3c701c1 · 2021-07-02T06:28:14.000-05:00
diff --git a/samples/job_with_aws_input_sample.js b/samples/job_with_aws_input_sample.js
@@ -75,7 +75,7 @@ async function createJobWithAWSInput() {
         // process and you can identify and refer to a specific input by the key assigned. For example we can add:
         sources["second-key"] = { "image": { 'bucket': BUCKET_NAME, 'key': FILE_KEY } };
         sources["another-key"] = { "image": { 'bucket': BUCKET_NAME, 'key': FILE_KEY } };
-        // If you send a wrong input key, the model fails to process the input.
+        // If you send an incorrect input key, the model fails to process the input.
         sources["wrong-key"] = { "a.wrong.key": { 'bucket': BUCKET_NAME, 'key': FILE_KEY } };
         // If you send a correct input key, but a wrong AWS S3 value key, the model fails to process the input.
         sources["wrong-value"] = { "image": { 'bucket': BUCKET_NAME, 'key': "wrong-aws-file-key.png" } };
diff --git a/samples/job_with_embedded_input_sample.js b/samples/job_with_embedded_input_sample.js
@@ -11,7 +11,7 @@ logger.level = "info";
 // The MODZY_BASE_URL should point to the API services route which may be different from the Modzy page URL.
 // (ie: https://modzy.example.com/api).
 const BASE_URL = process.env.MODZY_BASE_URL;
-// The MODZY_API_KEY is your own personal API key. It is composed by a public part, a dot character and a private part
+// The MODZY_API_KEY is your own personal API key. It is composed by a public part, a dot character, and a private part
 // (ie: AzQBJ3h4B1z60xNmhAJF.uQyQh8putLIRDi1nOldh).
 const API_KEY  = process.env.MODZY_API_KEY;
 
@@ -26,7 +26,7 @@ async function createJobWithEmbeddedInput(){
 	try {
 		// Get the model object:
         // If you already know the model identifier (i.e.: you got from the URL of the model details page or the input sample),
-        // you can skip this step. If you don't you can find the model identifier by using its name as follows:
+        // you can skip this step. If you don't, you can find the model identifier by using its name as follows:
         let model = await modzyClient.getModelByName("Multi-Language OCR");
         // Or if you already know the model id and want to know more about the model, you can use this instead:
 		//let model = await modzyClient.getModel("c60c8dbd79");
@@ -37,7 +37,7 @@ async function createJobWithEmbeddedInput(){
         logger.info(`The model identifier is ${model.modelId} and the latest version is ${model.latestVersion}`);
         // Get the model version object:
         // If you already know the model version and the input key(s) of the model version you can skip this step. Also, you can
-        // use the following code block to know about the inputs keys and skip the call on future job submissions.
+        // use the following code block to know about the input keys and skip the call on future job submissions.
         let modelVersion = await modzyClient.getModelVersion(model.modelId, model.latestVersion);
         // The info stored in modelVersion provides insights about the amount of time that the model can spend processing, the inputs, and
         // output keys of the model.
@@ -56,7 +56,7 @@ async function createJobWithEmbeddedInput(){
 
 		// Send the job:
 		// An embedded input is a byte array encoded as a string in Base64, that's very handy for small to middle size files, for
-		// bigger files can be a memory issue because you need to load the file in memory (load + encode), use submitJobFiles instead.
+		// bigger files can cause memory issues because you need to load the file in the memory (load + encode).
 		const imageBytes  = fs.readFileSync('samples/image.png');
 		let configBytes = fs.readFileSync('samples/config.json');
 		// With the info about the model (identifier), the model version (version string, input/output keys), you are ready to
@@ -65,10 +65,10 @@ async function createJobWithEmbeddedInput(){
 		// An inference job groups input data that you send to a model. You can send any amount of inputs to
 		// process and you can identify and refer to a specific input by the key that you assign, for example we can add:
 		sources["second-key"] = {"input": imageBytes, "config.json":configBytes}
-		// You don't need to load all the inputs from files, just convert to bytes as follows:
+		// You don’t need to load all the inputs from the files, just convert to bytes as follows:
 		configBytes = Buffer.from(JSON.stringify({"languages":["spa"]}));		
 		sources["another-key"] = {"input": imageBytes, "config.json":configBytes}
-		// If you send a wrong input key, the model fails to process the input.
+		// If you send an incorrect input key, the model fails to process the input.
 		sources["wrong-key"] = {"a.wrong.key": imageBytes, "config.json":configBytes}
 		// If you send a correct input key, but some wrong values, the model fails to process the input.
 		sources["wrong-value"] = {"input": configBytes, "config.json":imageBytes}
@@ -78,20 +78,20 @@ async function createJobWithEmbeddedInput(){
         // of the process, the most important being the job identifier and the job status.
         logger.info("job: "+job.jobIdentifier+" "+job.status);
         // The job moves to SUBMITTED, meaning that Modzy acknowledged the job and sent it to the queue to be processed.
-        // We provide a helper method to listen until the job finishes processing. it will listen until the job finishes 
+        // We provide a helper method to listen until the job finishes processing. It will listen until the job finishes 
         // and moves to COMPLETED, CANCELED, or TIMEOUT.        
         job = await modzyClient.blockUntilComplete(job);
         // Get the results:
         // Check the status of the job. Jobs may be canceled or may reach a timeout.
         if( job.status === "COMPLETED" ){
             // A completed job means that all the inputs were processed by the model. Check the results for each
-            // input keys provided in the source object to see the model output.
+            // input key provided in the source object to see the model output.
             let result = await modzyClient.getResult(job.jobIdentifier);
             // The result object has some useful info:
             logger.info(`Result: finished:  ${result.finished}, total: ${result.total}, completed: ${result.completed}, failed: ${result.failed}`);
             // Notice that we are iterating through the same input sources keys
             for( key in sources ){
-                // The result object has the individual results of each job input. In this case the output key is called
+                // The result object has the individual results of each job input. In this case, the output key is called
                 // results.json, so we can get the results as follows:
                 if( result.results[key] ){
                     let model_res = result.results[key]["results.json"];
diff --git a/samples/job_with_file_input_sample.js b/samples/job_with_file_input_sample.js
@@ -11,7 +11,7 @@ logger.level = "info";
 // The MODZY_BASE_URL should point to the API services route which may be different from the Modzy page URL.
 // (ie: https://modzy.example.com/api).
 const BASE_URL = process.env.MODZY_BASE_URL;
-// The MODZY_API_KEY is your own personal API key. It is composed by a public part, a dot character and a private part
+// The MODZY_API_KEY is your own personal API key. It is composed by a public part, a dot character, and a private part
 // (ie: AzQBJ3h4B1z60xNmhAJF.uQyQh8putLIRDi1nOldh).
 const API_KEY  = process.env.MODZY_API_KEY;
 
@@ -26,7 +26,7 @@ async function createJobWithFileInput(){
 	try {
 		// Get the model object:
         // If you already know the model identifier (i.e.: you got from the URL of the model details page or the input sample),
-        // you can skip this step. If you don't you can find the model identifier by using its name as follows:
+        // you can skip this step. If you don't, you can find the model identifier by using its name as follows:
         let model = await modzyClient.getModelByName("Multi-Language OCR");
         // Or if you already know the model id and want to know more about the model, you can use this instead:
 		//let model = await modzyClient.getModel("c60c8dbd79");
@@ -37,7 +37,7 @@ async function createJobWithFileInput(){
         logger.info(`The model identifier is ${model.modelId} and the latest version is ${model.latestVersion}`);
         // Get the model version object:
         // If you already know the model version and the input key(s) of the model version you can skip this step. Also, you can
-        // use the following code block to know about the inputs keys and skip the call on future job submissions.
+        // use the following code block to know about the input keys and skip the call on future job submissions.
         let modelVersion = await modzyClient.getModelVersion(model.modelId, model.latestVersion);
         // The info stored in modelVersion provides insights about the amount of time that the model can spend processing, the inputs, and
         // output keys of the model.
@@ -63,10 +63,10 @@ async function createJobWithFileInput(){
 		// An inference job groups input data that you send to a model. You can send any amount of inputs to
 		// process and you can identify and refer to a specific input by the key that you assign, for example we can add:
 		sources["second-key"] = {"input": imagePath, "config.json": configPath}
-		// You don't need to load all the inputs from files, just convert to bytes as follows:
+		// You don’t need to load all the inputs from the files, just convert to bytes as follows:
 		const configBytes = Buffer.from(JSON.stringify({"languages":["spa"]}));
 		sources["another-key"] = {"input": imagePath, "config.json":configBytes}
-		// If you send a wrong input key, the model fails to process the input.
+		// If you send an incorrect input key, the model fails to process the input.
 		sources["wrong-key"] = {"a.wrong.key": imagePath, "config.json":configPath}
 		// If you send a correct input key, but some wrong values, the model fails to process the input.
 		sources["wrong-value"] = {"input": configPath, "config.json":imagePath}
@@ -76,20 +76,20 @@ async function createJobWithFileInput(){
         // of the process, the most important being the job identifier and the job status.
         logger.info("job: "+job.jobIdentifier+" "+job.status);
         // The job moves to SUBMITTED, meaning that Modzy acknowledged the job and sent it to the queue to be processed.
-        // We provide a helper method to listen until the job finishes processing. it will listen until the job finishes 
+        // We provide a helper method to listen until the job finishes processing. It will listen until the job finishes 
         // and moves to COMPLETED, CANCELED, or TIMEOUT.        
         job = await modzyClient.blockUntilComplete(job);
         // Get the results:
         // Check the status of the job. Jobs may be canceled or may reach a timeout.
         if( job.status === "COMPLETED" ){
             // A completed job means that all the inputs were processed by the model. Check the results for each
-            // input keys provided in the source object to see the model output.
+            // input key provided in the source object to see the model output.
             let result = await modzyClient.getResult(job.jobIdentifier);
             // The result object has some useful info:
             logger.info(`Result: finished:  ${result.finished}, total: ${result.total}, completed: ${result.completed}, failed: ${result.failed}`);
             // Notice that we are iterating through the same input sources keys
             for( key in sources ){
-                // The result object has the individual results of each job input. In this case the output key is called
+                // The result object has the individual results of each job input. In this case, the output key is called
                 // results.json, so we can get the results as follows:
                 if( result.results[key] ){
                     let model_res = result.results[key]["results.json"];
diff --git a/samples/job_with_text_input_sample.js b/samples/job_with_text_input_sample.js
@@ -10,7 +10,7 @@ logger.level = "info";
 // The MODZY_BASE_URL should point to the API services route which may be different from the Modzy page URL.
 // (ie: https://modzy.example.com/api).
 const BASE_URL = process.env.MODZY_BASE_URL;
-// The MODZY_API_KEY is your own personal API key. It is composed by a public part, a dot character and a private part
+// The MODZY_API_KEY is your own personal API key. It is composed by a public part, a dot character, and a private part
 // (ie: AzQBJ3h4B1z60xNmhAJF.uQyQh8putLIRDi1nOldh).
 const API_KEY  = process.env.MODZY_API_KEY;
 
@@ -25,7 +25,7 @@ async function createJobWithTextInput(){
     try{
         // Get the model object:
         // If you already know the model identifier (i.e.: you got from the URL of the model details page or the input sample),
-        // you can skip this step. If you don't you can find the model identifier by using its name as follows:
+        // you can skip this step. If you don't, you can find the model identifier by using its name as follows:
         let model = await modzyClient.getModelByName("Sentiment Analysis");
         // Or if you already know the model id and want to know more about the model, you can use this instead:
         //let model = await modzyClient.getModel("ed542963de");
@@ -36,7 +36,7 @@ async function createJobWithTextInput(){
         logger.info(`The model identifier is ${model.modelId} and the latest version is ${model.latestVersion}`);
         // Get the model version object:
         // If you already know the model version and the input key(s) of the model version you can skip this step. Also, you can
-        // use the following code block to know about the inputs keys and skip the call on future job submissions.
+        // use the following code block to know about the input keys and skip the call on future job submissions.
         let modelVersion = await modzyClient.getModelVersion(model.modelId, model.latestVersion);
         // The info stored in modelVersion provides insights about the amount of time that the model can spend processing, the inputs, and
         // output keys of the model.
@@ -61,28 +61,28 @@ async function createJobWithTextInput(){
         // process and you can identify and refer to a specific input by the key that you assign, for example we can add:
         sources["second-key"] = {"input.txt": "Sometimes I really hate ribs"}
         sources["another-key"] = {"input.txt": "Born and raised in Pennsylvania, Swift moved to Nashville, Tennessee, at the age of 14 to pursue a career in country music"}
-        // If you send a wrong input key, the model fails to process the input.
+        // If you send an incorrect input key, the model fails to process the input.
         sources["wrong-key"] = {"a.wrong.key": "This input is wrong!"}
         // When you have all your inputs ready, you can use our helper method to submit the job as follows:        
         let job = await modzyClient.submitJobText(model.modelId,modelVersion.version, sources);
         // Modzy creates the job and queue for processing. The job object contains all the info that you need to keep track
         // of the process, the most important being the job identifier and the job status.
         logger.info("job: "+job.jobIdentifier+" "+job.status);
         // The job moves to SUBMITTED, meaning that Modzy acknowledged the job and sent it to the queue to be processed.
-        // We provide a helper method to listen until the job finishes processing. it will listen until the job finishes 
+        // We provide a helper method to listen until the job finishes processing. It will listen until the job finishes 
         // and moves to COMPLETED, CANCELED, or TIMEOUT.        
         job = await modzyClient.blockUntilComplete(job);
         // Get the results:
         // Check the status of the job. Jobs may be canceled or may reach a timeout.
         if( job.status === "COMPLETED" ){
             // A completed job means that all the inputs were processed by the model. Check the results for each
-            // input keys provided in the source object to see the model output.
+            // input key provided in the source object to see the model output.
             let result = await modzyClient.getResult(job.jobIdentifier);
             // The result object has some useful info:
             logger.info(`Result: finished:  ${result.finished}, total: ${result.total}, completed: ${result.completed}, failed: ${result.failed}`);
             // Notice that we are iterating through the same input sources keys
             for( key in sources ){
-                // The result object has the individual results of each job input. In this case the output key is called
+                // The result object has the individual results of each job input. In this case, the output key is called
                 // results.json, so we can get the results as follows:
                 if( result.results[key] ){
                     let model_res = result.results[key]["results.json"];
diff --git a/src/job-client.js b/src/job-client.js
@@ -115,7 +115,7 @@ class JobClient{
 
     /**
      *
-     * Create a new job for the model at the specific version with the text inputs provided.
+     * Create a new job for a specific model and version with the text inputs provided.
      *
      * @param {string} modelId - the model id string
      * @param {versionId} versionId - version id string
@@ -140,7 +140,7 @@ class JobClient{
 
     /**
      *
-     * Create a new job for the model at the specific version with the embedded inputs provided.
+     * Create a new job for a specific model and version with the embedded inputs provided.
      *
      * @param {string} modelId - the model id string
      * @param {string} versionId - version id string
@@ -188,7 +188,7 @@ class JobClient{
 
     /**
      *
-     * Create a new job for the model at the specific version with the embedded inputs provided.
+     * Create a new job for a specific model and version with the embedded inputs provided.
      *
      * @param {string} modelId - the model id string
      * @param {string} versionId - version id string
@@ -230,7 +230,7 @@ class JobClient{
 
     /**
      *
-     * Create a new job for the model at the specific version with the aws-s3 inputs provided.
+     * Create a new job for a specific model and version with the aws-s3 inputs provided.
      *
      * @param {string} modelId - the model id string
      * @param {string} versionId - version id string
@@ -261,7 +261,7 @@ class JobClient{
 
     /**
      *
-     * Create a new job for the model at the specific version with the jdbc query provided,
+     * Create a new job for a specific model and version with the jdbc query provided,
      *
      * Modzy will create a data source with the parameters provided and will execute
      * the query provided, then will match the inputs defined of the model with the columns
@@ -298,13 +298,13 @@ class JobClient{
 
     /**
      *
-     * Utility method that wait until the job finish.
+     * Utility method that waits until the job finishes.
      *
-     * This method first check the status of the job and wait until the job reach
-     * the completed/error status by passing through  the submitted and in_progress state.
+     * This method first checks the status of the job and waits until the job reaches
+     * the completed/error status by passing through the submitted and in_progress states.
      *
      * @param {Object} job The job to block
-     * @return {Object} A updated instance of the job in a final state
+     * @return {Object} an updated instance of the job in a final state
      * @throws {ApiError} if there is something wrong with the service or the call
      */
     blockUntilComplete(job) {

Original file line number	Diff line number	Diff line change
`@@ -115,7 +115,7 @@ class JobClient{`
`115`	`115`
`116`	`116`	`/**`
`117`	`117`	`*`
`118`		`- * Create a new job for the model at the specific version with the text inputs provided.`
	`118`	`+ * Create a new job for a specific model and version with the text inputs provided.`
`119`	`119`	`*`
`120`	`120`	`* @param {string} modelId - the model id string`
`121`	`121`	`* @param {versionId} versionId - version id string`
`@@ -140,7 +140,7 @@ class JobClient{`
`140`	`140`
`141`	`141`	`/**`
`142`	`142`	`*`
`143`		`- * Create a new job for the model at the specific version with the embedded inputs provided.`
	`143`	`+ * Create a new job for a specific model and version with the embedded inputs provided.`
`144`	`144`	`*`
`145`	`145`	`* @param {string} modelId - the model id string`
`146`	`146`	`* @param {string} versionId - version id string`
`@@ -188,7 +188,7 @@ class JobClient{`
`188`	`188`
`189`	`189`	`/**`
`190`	`190`	`*`
`191`		`- * Create a new job for the model at the specific version with the embedded inputs provided.`
	`191`	`+ * Create a new job for a specific model and version with the embedded inputs provided.`
`192`	`192`	`*`
`193`	`193`	`* @param {string} modelId - the model id string`
`194`	`194`	`* @param {string} versionId - version id string`
`@@ -230,7 +230,7 @@ class JobClient{`
`230`	`230`
`231`	`231`	`/**`
`232`	`232`	`*`
`233`		`- * Create a new job for the model at the specific version with the aws-s3 inputs provided.`
	`233`	`+ * Create a new job for a specific model and version with the aws-s3 inputs provided.`
`234`	`234`	`*`
`235`	`235`	`* @param {string} modelId - the model id string`
`236`	`236`	`* @param {string} versionId - version id string`
`@@ -261,7 +261,7 @@ class JobClient{`
`261`	`261`
`262`	`262`	`/**`
`263`	`263`	`*`
`264`		`- * Create a new job for the model at the specific version with the jdbc query provided,`
	`264`	`+ * Create a new job for a specific model and version with the jdbc query provided,`
`265`	`265`	`*`
`266`	`266`	`* Modzy will create a data source with the parameters provided and will execute`
`267`	`267`	`* the query provided, then will match the inputs defined of the model with the columns`
`@@ -298,13 +298,13 @@ class JobClient{`
`298`	`298`
`299`	`299`	`/**`
`300`	`300`	`*`
`301`		`- * Utility method that wait until the job finish.`
	`301`	`+ * Utility method that waits until the job finishes.`
`302`	`302`	`*`
`303`		`- * This method first check the status of the job and wait until the job reach`
`304`		`- * the completed/error status by passing through the submitted and in_progress state.`
	`303`	`+ * This method first checks the status of the job and waits until the job reaches`
	`304`	`+ * the completed/error status by passing through the submitted and in_progress states.`
`305`	`305`	`*`
`306`	`306`	`* @param {Object} job The job to block`
`307`		`- * @return {Object} A updated instance of the job in a final state`
	`307`	`+ * @return {Object} an updated instance of the job in a final state`
`308`	`308`	`* @throws {ApiError} if there is something wrong with the service or the call`
`309`	`309`	`*/`
`310`	`310`	`blockUntilComplete(job) {`