Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

You Can Use GhostDoc's Document This With JavaScript

DZone's Guide to

You Can Use GhostDoc's Document This With JavaScript

If you've used GhostDoc, then you know what it can do for you and your code. In this post, we look at how it can also be used with JavaScript. Read on for details!

· Integration Zone
Free Resource

Modernize your application architectures with microservices and APIs with best practices from this free virtual summit series. Brought to you in partnership with CA Technologies.

If you haven’t lived in a techie cave the last 10 years, you’ve probably noticed JavaScript’s rise to prominence. Actually, forget prominence. JavaScript has risen to command consideration as today’s lingua franca of modern software development.

I find it sort of surreal to contemplate that, given my own backstory. Years (okay, almost 2 decades) ago, I cut my teeth with C and C++. From there, I branched out to Java, C#, Visual Basic, PHP, and some others I’m probably forgetting. Generally speaking, I came of age during the heyday of object-oriented programming.

Image title

Oh, sure I had awareness of other paradigms. In college, I had dabbled with (at the time) the esoteric concept of functional programming. And I supplemented “real” programming work with scripts as needed to get stuff done. But object-oriented languages gave us the real engine that drove serious work.

Javascript fell into the “scripting” category for me, when I first encountered it, probably around 2001 or 2002. It and something called VBScript competed for the crown of “how to do weird stuff in the browser, half-baked hacky languages.” JavaScript won that battle and cemented itself in my mind as “the thing to do when you want an alert box in the browser.”

Even as it has risen to prominence and inspired a generation of developers, I suppose I’ve never really shed my original baggage with it. While I conceptually understand its role as “assembly language of the web,” I have a hard time not seeing the language that was written in 10 days and named to deliberately confuse people.

GhostDoc, Help, and Intellisense

I lead with all of this to help you understand the lens through which to read this post. As a product of the strongly typed, object-oriented wave of programmers, my subconscious still regards JavaScript as something of an afterthought, its dominance notwithstanding. And so when I see advances in the JavaScript world, I tend to think, “Oh, cool, you can do that with JavaScript too!”

I’ll come back to that shortly. But first, I’d like to remind you of a prominent GhostDoc feature. Specifically, I’m referring to the “Document This” capability. With your cursor inside of a method or type, you can use this capability to generate instant, well-formated, XML doc comments. Thoroughly documented code sits just a “Ctrl-Shift-D” away.

If you work with C# a lot and generate public APIs and/or help documentation, you will love this capability. It doesn’t absolve you of needing to add specific contest. But it does give you a thorough base upon which to build. For example, consider this method from my Chess TDD example codebase.

It Works With JavaScript, Too

Now, as I’ve said earlier, I don’t really play much in the JavaScript world. I generally focus on application code and server side stuff, delving into the realm of the client side browser only when necessary to get things done. So you can imagine my reaction to learn that GhostDoc can do this with JavaScript too. It can produce sophisticated XML doc comments that allow for use in generating help and with Intellisense.

Actually, if I really want to embarrass myself, I’ll confess that my initial reaction was, “JavaScript code has Intellisense?” I think maybe I knew that, but I assumed that such a thing would offer little value in a dynamically typed language. Shows what I know. But then, once I got over that initial wave of ignorance, I thought, “Cool!” at the idea that you could generate documentation for JavaScript. I then wondered if well-documented JavaScript was more or less rare than well documented C#. That jury has yet to come back, as far as I know.

Let’s Take a Look

Let’s take a look at what GhostDoc actually does here. To demonstrate, I created a branch of my ChessTDD project, to which I added an ASP MVC front end. This plopped some JavaScript right in my lap, in the form of the default files in the “Scripts” folder. To see this in action, I popped open modernizr-2.6.2.js and found a method upon which to experiment.

Image title

ShivMethods sounded… interesting, in a prison yard sort of way. As a publicly consumable library, it already has documentation. And, as I learned by playing around, that documentation already gets picked up by IntelliSense. But I figured I’d see what happened by using GhostDoc anyway, for comparison’s sake.

So I lazily put my cursor randomly inside the method and fired away with a Ctrl-Shift-D. Check it out.

Image title

As you can see, GhostDoc puts the comment inside of the method and behaves largely as it would with C#. In case you’re wondering about the stylistic difference, GhostDoc does this because it’s the more Microsoft-preferred way. To underscore that, look what happens now when we consume this method with IntelliSense.

Image title

As you can see, IntelliSense gives preference to the comments generated by GhostDoc.

The Takeaway

What’s my main point here?  I simply wanted to share that you can use GhostDoc for JavaScript just as you can with C# or VB.

Forget about my crotchety ways and biases. Your JavaScript/client-side code is every bit as important as what you write anywhere else. You should treat it as such when documenting it, creating help for it, and making sure users know how to consume your libraries. So make sure you’ve got Ctrl-Shift-D at the ready when using Visual Studio, regardless of where the code gets executed.

The Integration Zone is proudly sponsored by CA Technologies. Learn from expert microservices and API presentations at the Modernizing Application Architectures Virtual Summit Series.

Topics:
code ,ghostdoc ,javascript ,programming ,integration

Published at DZone with permission of Erik Dietrich, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}