JSDOCed Javascript

Test your code with jsdoc

jsdoced.js will automatically extract jsdoc from your code. Using your jsdoc comments, it will generate another javascript file which makes sure your jsdoc is respected during execution.

The more you documents your code, the safer it becomes.

Detect New Family of Bugs

Before, jsdoc comments were not used to test your code. So you will likely find new bugs thanks to it. And it is a good news! You want to find those bugs before your users see them :)

Automatic Generation

The jsdoc will automatically be extracted from your javascript source. Your jsdoc comments will be used to produce another version of your source, modified to check your jsdoc during execution. It is all done for you.

Javascript to Javascript

It is all pure javascript here. jsdoc is the established way to document javascript. No new language! It works in node.js and browser. It can even generate sourcemap.

Why using jsdoced.js?

Suppose you are a CTO, why would you choose to use jsdoced.js ? [slides]

jsdoced.js - Step by Step

The slides presents the practical steps to show you how your code can be improved with jsdoced.js. [slides]




Get A Function

Here is our example function. This is a simple function which measure the length of a string. There is jsdoc comment which provides details on the function: The type of arguments and the type returned.

/**
 * measure the length of a string
 *
 * @param  {String} aString the string to measure
 * @return {Number} the length of the string
 */
var stringLength  = function(aString){
    return aString.length
}



# Install jsdoced.js
$ npm install -g jsdoced.js

# Generate the better.js automatically
$ jsdoced.js file.js -o file.jsdoced.js 

Convert .js files into .jsdoced.js

jsdoced.js analyses your code and extract jsdoc. It produces a .jsdoced.js file with the additional code to check if your jsdoc is respected at runtime.




Here is the .better.js file

On the right you can see the produced code. The original function is wrapped in a Better.Function with all the types informations properly declared. So be sure to include better.js. Thus if your jsdoc isn't respected during execution, you will be warned imediatly!

/**
 * measure the length of a string
 *
 * @param  {String} aString the string to measure
 * @return {Number} the length of the string
 */
var stringLength = Better.Function(function(aString){
    return aString.length
}, {
    arguments: [String],
    return: Number
})



/**
 * measure the length of a string
 *
 * @param  {String} aString - the string to measure
 * @return {Number} the length of the string
 */
var stringLength  = function(aString){
    return aString.length
}

Use JSDOC To Test Your Code

JSDOC contains valuable informations on the behavior of your code. It was destined to programmers before. Now we use it with computers to extract more informations on how to test your code.




Detect Typing Error In Javascript

The tags @param are analysed to know which type is ok for this arguments No more 'oops i forgot an argument' bug. We do the same for @return, thus we test the function behavior too.

/**
 * measure the length of a string
 *
 * @param  {String} aString - the string to measure
 * @return {Number} the length of the string
 */
var stringLength  = function(aString){
    return aString.length
}



/**
 * a cat with its age
 *
 * @constructor
 * @param  {Number} age - the age of the cat
 */
var Cat  = function(age){
    this._age = age
}

Detect Private Errors in JS

All your JSDOC @constructor tag are detected to know what your classes are and enable Better.Class privates. Thus if your classes private are used outside your class, you will be warned immediatly




# in node.js
var Better = require('better.js');

# in browser
< script href='better.js'>< /script>

Run in node.js and browser

It runs in node.js and modern browsers. Thus you can test your javascript in various environments you are running on.




100% plain old javascript

better.js is pure 100% javascript. And jsdoc is the established way to document javascript. Not a new language to learn, find documentation for, find tools for! So everything is already well-known so it is painless to integrate. Checkout betterjs cache folder workflow. Heck, it can even generate sourcemap.

.

# Javascript is open standard

# Javascript is run everywhere

# =>

# You can't beat that!



/**
 * measure the length of a string
 *
 * @param  {String} aString - the string to measure
 * @return {Number} the length of the string
 */
var stringLength  = function(aString){
    return aString.length
}

More docs means safer code

With jsdoced.js, writing jsdoc comments is like writing tests. Writing docs is good, Testing code is good. It creates a virtuous circle "The more you documents your code, the safer it becomes."

The "Obvious" Slides [link]

It introduces jsdoced.js. What is it ? How it can be useful? How you can use it ? I tried to make it as obvious as possible.




The "Analysis" Slides [link]

It presents the advantages and disavantages of jsdoced.js.

The "Video" Slides [slides] [video]

jsdoced.js will automatically extract jsdoc from your code. Using your jsdoc comments, it will generate another javascript file which makes sure your jsdoc is respected during execution.