We Keep Coding

How to create hints for personal functions in VS Code

I want to make a personal library with all my js functions written.
What I really need is that I need the intellisense of VS Code to show me more hints about this functions - type of the input variables, type of the return, maybe some information about the function.
For example - a hint for substring looks like this:
and a hint for my function looks like this:
Digging a bit in VS Code I was able to find, that there are .ts files with declaration of objects, interfaces and functions (for example declaration of substring() in lid.es6.d.ts, etc.)
My first thought is whether I can make a personal .ts file with declaration of all my functions and make the intellisense refer to it too.

You don't need a .d.ts for your javascript functions, you can just use a jsDoc comment. Ex:
/**
* Does stuff
* #param {Number} params
*/
function myFun(params) {
}
Between {} is the type of the parameter. You can also add a description to your function.
VsCode will pick-up JsDoc comments and use them to show you hints. Also if you type /** and then press tab above a function it will insert a property formatted jsDoc comment base on your function to give you a starting point.
JsDoc reference here
Note: Give typescript a try, you will get the nice hints you are looking for because Typescript allows you to specify the argument types, also the output of typescript is plain TS, so you will be able to use your library anywhere you could have used it before

Yes you could write your own typings. If you don't want to use TS, you can use the JSDoc standard:
/**
* Get a survey's details and possible answers by id
* #param {Number} surveyId
*/
const getById = async (surveyId) => {
...
}
VSC is smart enough to read all that and display it when implementing.
Especially when you build services which are exported and the imported this works great.
JSDoc info: http://usejsdoc.org/about-getting-started.html

VSCode AngularJS intellisense

So with the new language service Salsa nearing completion (Available in 1.8.0-insider with a few environment variables set) You can get intellisense support with jsDoc comments. This is thanks to TypeScripts support for it.
However my issue is continuing that into an AngularJS service, or controller for custom types. Just to note this is for JavaScript code, not TypeScript.
Let me quickly demonstrate my setup to hopefully explain.
I define my services, controller etc as CommonJS modules (To enable framework independent code reuse, and easier organisation)
//service.js
/**
* #typedef {Object} someObj
* #prop {int} value
*/
/**
* Do some action
* #param {string} val
* #returns {someObj}
*/
exports.test = function(val) {
return {};
}
When i require this anywhere in my project VSCode picks up the JSdoc comments and gives me correct intellisense, brilliant.
So traditionally i would plug that into angular like:
angular.module('myModule').service('service', () => require('./service'));
Now is where my wonderful new intellisense dreams are crushed.
Understandably when i inject that service anywhere all intellisense is lost as VSCode nor TypeScript can be expected to understand the intricacies or every frameworks DI systems.
So I'm left a little stumped.
I had the thought of creating typing's just for the angular wrappers around my services, controllers. However upon researching it i couldn't find anyway of getting the types defined in the world of JSDoc into my definition files (I'm not a TypeScript guy).
I also had the thought of using #module syntax of jsDoc to define all my CommonJs services, controllers etc. Then using that module to set the type of each function parameter where I'm injecting in my custom modules, However I'm not entirely sure that would work looking at the docs. It seems you have to specify your #module tag with the path expected in your require call which wouldn't work with relatively required modules where that path would change. Nor does the docs mention being able to use it in the #Param tag to say this variable is this module.
The other option i considered was some extension that helps VSCode's intellisense by providing the missing link. Consume the known intellisense info when defining the service and passing it onto the instances where that service is injected. However i couldn't find any such extension, nor even if it would be possible to create.
With the advances in VSCode's intellisense thanks to Salsa and typescript is this at all possible? I had got my hopes up with the JSDoc support, but i guess too soon.
Any help would be greatly appreciated, that or any workarounds where i could change my way of working slightly to get the desired result.

JavaScript intellisense in Visual Studio only partially working

I'm seeing some strange behaviour with JavaScript intellisense in Visual Studio 2013 Express for Web. I followed all the advice I could google, and it's almost working perfectly.. but something to do with being inside or outside of a function seems to be affecting it. I am very new to JavaScript, so I might be missing something, but this doesn't make any sense to me:
Outside of a function it seems to work partially...
(I get one level of intellisense)
(but not two)
But inside of a function it works perfectly...
(I get all intellisense)
In a separate file, I get a similar problem, but down one function level...
(limited here)
(but everything here)
Any advice would be much appreciated!

OK I've looked through the code here's what I think.
Within Phaser.Game you have this code
/**
* #property {Phaser.GameObjectFactory} add - Reference to the Phaser.GameObjectFactory.
*/
this.add = null;
Because this is initially set to null I'm guessing Visual Studio will not be able to infer what type "add" will be since it is only determined at run time.
If add(...) was defined as Phaser.Game.prototype.add = function() { ... } or even within the function using this.add = function() { ... } I think you would see it in intellisense (this is normally how classes are built in Javascript). However I notice you are defining it dynamically later in the code like this from a factory:
this.add = new Phaser.GameObjectFactory(this);
Visual Studio isn't smart enough to know this is the definition of add(...) it should use for intellisense.
In the second example game is passed as an argument, and visual studio is not smart enough to work out what type this will be. Because Javascript is weakly-typed the argument could be a Game, but could also be an integer, boolean or anything else for that matter.

How can I use closure type annotation with Aptana?

If I enter the follow JavaScript code in Aptana Studio 3 then I expect some errors but it show nothing.
/**
* #type {string}
*/
var abc = 23;
abc.doesNotExists();
How can I enable the support for closure type annotation?

Currently Aptana supports only the annotations but not also the actual type checking. In order to type check you have to compile that code using the google closure compiler. If you set the compiler to the full optimized mode it will yell the warning that abc is a string ( as you placed it in the annotation comment ), but you have set a number value instead. In order to be able to take this from the command line of the closure compiler and integrate it into aptana you would need a plugin, but as far as i know, the closure plugin for eclipse/aptana has not been updated for the last 1 or 2 years, and also this feature that you would like to have was not implemented in the latest release of that plugin.
In other words, either you run the closure compiler separately and check the for warnings or errors in certain files, OR you fork the repo of the eclipse closure plugin and implement this feature yourself.
I had the same issue as you, but having too much work to do pushed me into opting for the first solution ( running the closure compiler separately in a console ). I had even placed a hook so each time i would save a file in that project it would run the compiler in the console view of aptana so i could check if i had introduced new errors or warnings.

_Best Practices for JSDoc'ing Javascript files written in the "revealing module pattern" Style? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Most of my Javascript functions are relatively simple, and called for their sideeffects: I use jQuery to manipulate the DOM or make Ajax-calls. I prefer to write my functions in the "revealing module pattern" style.
I just discovered that JSDoc- annotating Javascript files has a benefit: with the help of the annotations, Eclipse's JS Development Tools can parse my JS file and fill the Eclipse Outline View (which would otherwise be empty).
Now I wonder what are the fine points, or the good practices of annotating? I am not used to it.
The google JS style guide says something about JSDoc:
recommends to only use a subset of available tags, among other advice.
For now, I came up with this template (this code does not do anything useful):
/**
* #fileOverview Say something meaningful about the js file.
* #author My name
* #version 1.0.1
*/
/**
* #namespace What the namespace contains or which apps/webpages use it
*/
if (!window['my']['namespace']) {
window['my']['namespace'] = {};
my.namespace = (function() {
/**
* Documentation string...
* #memberOf window.my.namespace
* #private
*/
var clear = function(){};
/**
* Documentation string...
* #memberOf window.my.namespace
* #public
*/
function delete_success(data){
var str = "# of files affected: " + data.length;
$('<pre id="success"/>').html(str).appendTo('#del_0b');
$('<pre id="success"/>').html(data.result).appendTo('#del_sf');
}
//more code
return {
"method1": method1,
"delete_success" : delete_success
};
})(); //my.namespace
} //end if
Am I supposed to use JSDoc tag #function or #memberOf here, or both?
What about the #field tag?
Should the return clause be JSDoc'umented as well? With which tags?
Should I really not use the #public tag? I find it useful here.
Any recommendations?
Does anyone know a good, practical JSDoc style guide for small projects?

If you're looking for code samples, I've found that the best place to find them is in the archives of the jsdoc-users Google Group. I've had much better luck there than searching Google, and if you ask a question they're usually pretty good about helping out.
I can't speak for the Eclipse support, but there is a new version of jsdoc, jsdoc3. Check out the documentation here. It's a little incomplete, but I know they have updates written and ready for review, so they should be improving soon.
Regarding your specific question regarding #function and #memberof, you'll likely want to use #function, not #memberof for simple function documentation.

In Eclipse #memberOf (with capital O) does the trick for the outline (Ctrl+O shortcut). I use JSDoc mostly for the Eclipse outline, but I also use #author for humans :)
I also use #private on private functions.
IMHO JSDT is OK but not very helpful, it did not evolve much lately.
You should use an Eclipse JSHint plugin or use TypeScript with an Eclipse plugin (you can do refactoring but adds some complexity).

for me (Eclipse 4.3 Kepler) the following works fine:
my.namespace.foo.AbstractClass = {
/** #memberOf my.namespace.foo.StaticClass <- this statement already
* fixes the Eclipse Outline and Package Views for all other members
*/
staticMethod1 : function() { /* ... */ },
/** no need to add some JSDoc here for the Outline etc. */
staticMethod2 : function() { /* ... */ }
}
(for "non-abstract" classes, speaking Java, it should be similar)
which is nice because:
it's almost the minimum to not repeat the namespace or JSDoc tags all over
I do not have to fiddle around with prototype or this
the "abstract class"1 is immediately created
1: I know - everything is object - but I feel better with stronger typed and namespaced environments/clearer/more defined concepts like in Java. The whole JavaScript stuff is just grown and (IMHO) really bad and hard to work with in bigger environments with multiple programmers and solid refactoring support, good maintainability, testability, modularity, dependency management, self documentation etc.