chore: write js doc

ui/app/components/job-editor.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
+// @ts-check
 import Component from '@glimmer/component';
 import { inject as service } from '@ember/service';
 import { action } from '@ember/object';
@@ -11,13 +12,22 @@ import messageFromAdapterError from 'nomad-ui/utils/message-from-adapter-error';
 import localStorageProperty from 'nomad-ui/utils/properties/local-storage';
 import { tracked } from '@glimmer/tracking';
 
+/**
+ * JobEditor component that provides an interface for editing and managing Nomad jobs.
+ *
+ * @class JobEditor
+ * @extends Component
+ */
 export default class JobEditor extends Component {
   @service config;
   @service store;
 
   @tracked error = null;
   @tracked planOutput = null;
 
+  /**
+   * Initialize the component, setting the definition and definition variables on the model if available.
+   */
   constructor() {
     super(...arguments);
 
@@ -35,6 +45,11 @@ export default class JobEditor extends Component {
     }
   }
 
+  /**
+   * Check if the component is in editing mode.
+   *
+   * @returns {boolean} True if the component is in 'new' or 'edit' context, otherwise false.
+   */
   get isEditing() {
     return ['new', 'edit'].includes(this.args.context);
   }
@@ -44,6 +59,9 @@ export default class JobEditor extends Component {
     this.args.job.set('_newDefinition', this.definition);
   }
 
+  /**
+   * Enter the edit mode and defensively set the definition on the model.
+   */
   @action
   edit() {
     this.setDefinitionOnModel();
@@ -55,6 +73,11 @@ export default class JobEditor extends Component {
     this.args.onToggleEdit(false);
   }
 
+  /**
+   * Determine the current stage of the component based on the plan output and editing state.
+   *
+   * @returns {"review"|"edit"|"read"} The current stage, either 'review', 'edit', or 'read'.
+   */
   get stage() {
     if (this.planOutput) return 'review';
     if (this.isEditing) return 'edit';
@@ -68,6 +91,10 @@ export default class JobEditor extends Component {
     this.shouldShowPlanMessage = false;
   }
 
+  /**
+   * A task that performs the job parsing and planning.
+   * On error, it calls the onError method.
+   */
   @(task(function* () {
     this.reset();
 
@@ -87,6 +114,10 @@ export default class JobEditor extends Component {
   }).drop())
   plan;
 
+  /**
+   * A task that submits the job, either running a new job or updating an existing one.
+   * On error, it calls the onError method and resets our planOutput state.
+   */
   @task(function* () {
     try {
       if (this.args.context === 'new') {
@@ -109,6 +140,13 @@ export default class JobEditor extends Component {
   })
   submit;
 
+  /**
+   * Handle errors, setting the error object and scrolling to the error message.
+   *
+   * @param {Error} err - The error object.
+   * @param {"parse"|"plan"|"run"} type - The type of error (e.g., 'parse', 'plan', 'run').
+   * @param {string} actionMsg - A message describing the action that caused the error.
+   */
   onError(err, type, actionMsg) {
     const error = messageFromAdapterError(err, actionMsg);
     this.error = { message: error, type };
@@ -127,6 +165,13 @@ export default class JobEditor extends Component {
     }
   }
 
+  /**
+   * Update the job's definition or definition variables based on the provided type.
+   *
+   * @param {string} value - The new value for the job's definition or definition variables.
+   * @param {_codemirror} _codemirror - The CodeMirror instance (not used in this action).
+   * @param {"hclVariables"|"job"} [type='job'] - The type of code being updated ('job' or 'hclVariables').
+   */
   @action
   updateCode(value, _codemirror, type = 'job') {
     if (!this.args.job.isDestroying && !this.args.job.isDestroyed) {
@@ -138,6 +183,11 @@ export default class JobEditor extends Component {
     }
   }
 
+  /**
+   * Read the content of an uploaded job specification file and update the job's definition.
+   *
+   * @param {Event} event - The input change event containing the selected file.
+   */
   @action
   uploadJobSpec(event) {
     const reader = new FileReader();
@@ -149,6 +199,11 @@ export default class JobEditor extends Component {
     reader.readAsText(file);
   }
 
+  /**
+   * Get the definition or specification based on the view type.
+   *
+   * @returns {string} The definition or specification in JSON or HCL format.
+   */
   get definition() {
     if (this.args.view === 'full-definition') {
       return JSON.stringify(this.args.definition, null, 2);
@@ -157,6 +212,12 @@ export default class JobEditor extends Component {
     }
   }
 
+  /**
+   * Convert a JSON object to an HCL string.
+   *
+   * @param {Object} obj - The JSON object to convert.
+   * @returns {string} The HCL string representation of the JSON object.
+   */
   jsonToHcl(obj) {
     const hclLines = [];
 

ui/app/controllers/jobs/job/definition.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
+// @ts-check
 import Controller from '@ember/controller';
 import { action } from '@ember/object';
 import { alias } from '@ember/object/computed';
@@ -11,6 +12,10 @@ import { tracked } from '@glimmer/tracking';
 import classic from 'ember-classic-decorator';
 import WithNamespaceResetting from 'nomad-ui/mixins/with-namespace-resetting';
 
+/**
+ * Controller for handling job definition and specification, along with editing state and view.
+ * @augments Controller
+ */
 @classic
 export default class DefinitionController extends Controller.extend(
   WithNamespaceResetting
@@ -28,15 +33,27 @@ export default class DefinitionController extends Controller.extend(
 
   @service router;
 
+  /**
+   * Get the context of the controller based on the editing state.
+   * @returns {"edit"|"read"} The context, either 'edit' or 'read'.
+   */
   get context() {
     return this.isEditing ? 'edit' : 'read';
   }
 
+  /**
+   * Toggle the editing state.
+   * @param {boolean} [bool] - Optional boolean value to set the editing state.
+   */
   @action
   toggleEdit(bool) {
     this.isEditing = bool || !this.isEditing;
   }
 
+  /**
+   * Update the view based on the selected view.
+   * @param {"job-spec" | "full-definition"} selectedView - The selected view, either 'job-spec' or 'full-definition'.
+   */
   @action
   selectView(selectedView) {
     this.view = selectedView;

ui/app/routes/jobs/job/definition.js

@@ -3,9 +3,19 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
+// @ts-check
 import Route from '@ember/routing/route';
 
+/**
+ * Route for fetching and displaying a job's definition and specification.
+ */
 export default class DefinitionRoute extends Route {
+  /**
+   * Fetch the job's definition, specification, and variables from the API.
+   *
+   * @returns {Promise<Object>} A promise that resolves to an object containing the job, definition, format,
+   *                            specification, variableFlags, and variableLiteral.
+   */
   async model() {
     const job = this.modelFor('jobs.job');
     if (!job) return;
@@ -36,6 +46,12 @@ export default class DefinitionRoute extends Route {
     };
   }
 
+  /**
+   * Reset the controller when exiting the route.
+   *
+   * @param {Controller} controller - The controller instance.
+   * @param {boolean} isExiting - A boolean flag indicating if the route is being exited.
+   */
   resetController(controller, isExiting) {
     if (isExiting) {
       const job = controller.job;
@@ -45,6 +61,12 @@ export default class DefinitionRoute extends Route {
     }
   }
 
+  /**
+   * Set up the controller with the model data and determine the view type.
+   *
+   * @param {Controller} controller - The controller instance.
+   * @param {Object} model - The model data fetched in the `model` method.
+   */
   setupController(controller, model) {
     super.setupController(controller, model);