You Can Use GhostDoc's Document This With JavaScript

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.

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.

/// <summary>

///  Gets the moves from.

/// </summary>

/// <param name="startingLocation">The starting location.</param>

/// <param name="boardSize">Size of the board.</param>

/// <returns>IEnumerable<BoardCoordinate>.</returns>

public override IEnumerable<BoardCoordinate> GetMovesFrom(BoardCoordinate startingLocation, int boardSize = Board.DefaultBoardSize)

{

    var oneSquareAwayMoves = GetAllRadialMovesFrom(startingLocation, 1);

    return oneSquareAwayMoves.Where(bc => bc.IsCoordinateValidForBoardSize(boardSize));

}

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.

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.

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.

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.