dhis2-devs-core team mailing list archive

[Morten Olav Hansen <mortenoh@xxxxxxxxx>]

Hi everyone

Just wanted to tell you about JSDoc [1], its a documentation format for
documenting JavaScript code, I'm already using it in dhis2.period.js, and
it has many benefits.

The most obvious benefit is proper autocompletion and also type handling,
as an example, please consider this:

function hello(a,b,c) {}
hello(1,2,3);

The JS compiler/evaluator have no idea how to interpret the parameters to
this function since JS is not type aware by default. So it will just accept
anything.

Then please consider this:

/**
  * @param {String} a String parameter
  * @param {Number} a number
  * @param {Number} Another number
  */
function hello(a,b,c) {}
hello(1,2,3);

Now the IDE will say that the first argument is wrong, since it expected a
string to be passed, but argument 2 and 3 is correct.

I can only vouch for IntelliJ's handling of this, but I'm going to assume
Eclipse have similar mechanics in place.

For our D2js library, we will be using JSDoc all over the place, which will
make it a lot easier to use within an IDE.

[1] http://usejsdoc.org/

--
Morten