Skip navigation

It would be cool if ServiceNow (1) had an API for contextual code-completion, or (2) supported JSDoc

score 6
You have not voted. Active

JSdoc is a standards-based markup language, used to annotate JavaScript source code. JSDoc markup syntax is defined over at usejsdoc.org. Here is an example of a function documented with JSDoc:

 

/**
 * @description Iterates over a GlideRecord object that has already had a query run on it (.query()), and returns an array of the sys_ids for all GlideRecords returned from the included query.
 * @param gr {GlideRecord} A GlideRecord that .query() has already been called on, that is ready to have the .next() method called.
 * @returns {array} An array of the sys_ids for every record returned from the query on the passed-in GlideRecord
 */
function getSysIDs(gr) {
   var sysIds = [];
   while (gr.next()) {
  sysIds.push(gr.getUniqueValue());
   }
   return sysIds;
}

 

In most IDEs, it's possible to do a documentation lookup on any function that's documented with JSDoc. The documentation for the above function looks something like this:

 

 

Since JavaScript is loosely typed language, it can be very difficult sometimes to know how to interact with an API, without reading through it thoroughly. Doubly so for custom script includes!

 

Recently, ServiceNow has introduced the fantastic intellisense-style auto-completion and method description pop-ups with the use of CTRL+Space

And that's got me wondering - If our methods are well-documented using an appropriate standard like JSDoc, could we include support for describing public methods of Script Includes (via JSDoc), and have this intellisense completer and documentation tool display that as well?

 

For example, imagine I define a Script Include like so:

 

var TimeZoneUtils = Class.create();
TimeZoneUtils.prototype = {
   
   /**
  * Upon initialization, you can pass in a GlideDateTime object you've already created and set to a specific time.
  * The reference to this object will be used, and your GDT will be modified in-place. Alternatively, you may choose
  * not to specify a parameter upon initialization, and a new GlideDateTime object will be created, used, and returned
  * with the current time in the specified time-zone.
  *
  * @param {GlideDateTime} [gdt] - A reference to the (optional) GlideDateTime object to be modified IN-PLACE.
  * If not specified, a new one will be generated, and a reference returned.
  */
   initialize: function(gdt) {
   if (gdt) {
   this.gdt = gdt;
   } else {
   this.gdt = new GlideDateTime();
   }
  },
   
   /**
  * Get the GlideDateTime object (as a reference).
  * This will return a *reference* to the GlideDateTime object. Note that because of JavaScript's
  * pass-by-reference jive, you should expect that if you set a variable using this method, then
  * call another method which modifies the GDT object referenced in this class, you will be modifying
  * the object to which your variable is a reference! In other words, your variable will be modified *in-place*.
  * @returns {*|GlideDateTime}
  */
   getGDT: function() {
   return this.gdt;
   },
   
  /* OTHER STUFF HERE THIS IS JUST AN EXAMPLE */

   type: 'TimeZoneUtils'
};

 

So with this Class, perhaps the auto-completer could work something like this (see comments):

 

var gdtNow = new GlideDateTime();
var tzUtil = new TimeZoneUtils(gdt); //This could be auto-completed, showing the
  // JSDoc description and param information from the initialize function.
gdtNow = tzUtil.getGDT(); //This has no params but could show the description
  // from the JSDoc and auto-complete the method name if the user hits 
  // CTRL+Space on the tzUtil object.

 

What do you guys think? Is there value in extending the auto-completion and documentation display to include OOB and custom Script Includes? Please share your thoughts in the comments, and vote your opinion!

Comments

Vote history