Share Spotlight: SNDocs

#Share , #Share Spotlight , #Documentation , #Callum Ridley

Andrew Barnes

3 minute read

Share Spotlight

Welcome to the latest share spotlight! Every Friday we will be spotlighting a project from the Share site on the Developer Portal.

SNDocs

For this installment, we are featuring a project called SNDocs authored by Callum Ridley. This project adds a couple of script includes and a global UI Action. The goal of this share item is to bring some functionality that is similar to JSDoc. This appears to be an excellent 1.0 version that I myself would like to contribute to improving. It does not automate the writing of the documentation. That is left up to the developers to do as they are coding, but it does present the documentation in a very nice portal that is styled after our developer site API documentation.

Portal

Here is an example of the code commenting you need to provide in order to take advantage of this functionality.

/**SNDOC
@name _parseComment
@private
@description Parses over an individual comment with the tag parsers
@param {string} [comment] - a single comment as a string to parse over
@returns {object} An object will properties for each of the tags in the comment
*/
_parseComment: function(comment){

If you are familiar with JSDoc this will feel right at home as a developer. While this does not provide any automatic documenting, it can certainly be eased into your development practices and then have an ever growing source of documentation for your ServiceNow instances. To aid in getting the templating correctly there are two editor macros that are provided. You can get details about these by opening the Instance API Reference portal and clicking help. This first is sndoc - which provides the template for starting your documentation process. The other provided macro is sndocmethod, which just adds a stub for the function declaration in addition to the documentation. I would like to note that I love the additional use of script macros. The out of box syntax editor macros “vargr” and “for” are my most used.

Discover Dependent Scripts

The discover Dependent Scripts button on the function documentation is of particular interest. The author notes it might have some false positives due to the nature of the search it is performing, but it appears to be quite a good start. I would like to see this functionality improved upon and even crawl dependencies to deliver a map of affected areas when editing a script. Hopefully, Callum is up for some improvements to this feature because it shows great promise.

Thank you for your contribution Callum. If you want to comment on this or any of our Friday Share Spotlight items, feel free to use this thread on the community. You are welcome to reach out to me to help point me in the direction of a share item you think deserves spotlighting in the future.

Keep an eye on this space as every Friday we will provide a spotlight to another project on the Share site we think is worthy of attention. Have fun exploring!

Comments