DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
Securing Your Software Supply Chain with JFrog and Azure
Register Today

Trending

  • How to Submit a Post to DZone
  • DZone's Article Submission Guidelines
  • Is Podman a Drop-In Replacement for Docker?
  • Structured Logging

Trending

  • How to Submit a Post to DZone
  • DZone's Article Submission Guidelines
  • Is Podman a Drop-In Replacement for Docker?
  • Structured Logging
  1. DZone
  2. Coding
  3. JavaScript
  4. You Can Use GhostDoc's Document This With JavaScript

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!

Erik Dietrich user avatar by
Erik Dietrich
CORE ·
Jul. 06, 17 · Tutorial
Like (3)
Save
Tweet
Share
3.65K Views

Join the DZone community and get the full member experience.

Join For Free

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.

/// <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));

}

I took that un-commented method and used GhostDoc to generate this. Now, I should probably update the summary, but I really don’t see any other deficiencies here. It nails the parameter names and it even escapes the generic return type for readability.

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.

JavaScript code style

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

Opinions expressed by DZone contributors are their own.

Trending

  • How to Submit a Post to DZone
  • DZone's Article Submission Guidelines
  • Is Podman a Drop-In Replacement for Docker?
  • Structured Logging

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: