I like using JsDoc, as it gives me a lot of help when using WebStorm (or other IntelliJ derivates), such as parameter lookup, quick access to documentation, etc.
Most examples assume that you can write something like
/** #class MyClass */
var MyClass = function() {
}
But if you wrap your code in anonymous functions to avoid polluting the namespace (say, due to concatenating the js files), then WebStorm no longer finds the documentation, and I no longer get much help.
Is there any way around this?
Related
I thought about creating an extension that offers IntelliSense (i.e. code completion) for CoffeeScript, a popular language that compiles to JavaScript. By IntelliSense I primarly mean autocompletion: Properties, function parameters, automatic imports. If possible, also Go-To-Definitions. Despite its huge success and age, nothing like it exists in any IDE for CS, as far as I know. This is arguably because integrating the language server, import scanning, function signature analysis etc. are complex and this is not an easy task per se.
However, CoffeeScript natively and efficiently compiles into JavaScript, and JS Intellisense in VSCode is splendid. For a very basic yet mostly functional extension, the following approach sounds feasible:
Register completion item provider for type CoffeeScript files
When providing a completion item, take the compiled JavaScript code, get profuse IntelliSense information from the JS/TS language server (how? do I need my own instance? I don't think VSC even uses an actual JS LSP internally?) and show it in the CoffeeScript file cursor position
It does not sound difficult, but I don't know how to proceed. Here is a pseudo code snippet of how I imagine it to work:
class Provider {
provideCompletionItems(document, position, token) {
const word = document.getText(document.getWordRangeAtPosition(position))
const text = document.getText().split('\n')
const currentLineno = position.line
const textWithoutCurrentLine = text.filter((line, lineno) => lineno != currentLineno)
const compiled = CoffeeScript.compile(textWithoutCurrentLine.join('\n'), { sourceMap: true })
const currentLinenoJS = compiled.sourceMap[currentLine].lineno // don't know the syntax yet
const compiledWithWord = compiled.js.split('\n').splice(currentLinenoJS, 0, word)
// These methods don't exist, what do I do?
const JSProvider = vscode.languages.simulateCompletionItemProvider('javascript')
const completionItems: CompletionItem[] = JSProvider.getCompletionItemsForTextAndLine(textWithoutCurrentLine, currentLinenoJS)
return completionItems
}
}
vscode.languages.registerCompletionItemProvider('coffeescript', Provider));
This might be more confusing than helpful, but it's what the code could look like. I would love a hint on how to access the JavaScript intellisense features for dynamically generated code, from within the completion item provider handler of a CoffeeScript file. If this is doable, it would allow for simple extensions for similar compile-to-JS languages too.
In other words: JS has all these amazing autocompletion features and CS compiles to JS, including source maps. How can I leverage this to get autocompletion for CS?
Register completion item provider for type CoffeeScript files
This would be following programmatic language features. For a middleware kind of extension there are two main architectures possible, outlined here: Language services or request forwarding.
I eventually went with implementing a language service extension, outlined here.
This approach was significantly easier than writing a native analyzer.
When providing a completion item, take the compiled JavaScript code, get profuse IntelliSense information from the JS/TS language server (how? do I need my own instance?
Yes
I don't think VSC even uses an actual JS LSP internally?)
Yes, tsserver does not implement LSP, but offers its own APIs, but there are other usable implementations. So you need to interact with either of those.
I have a jenkins.gdsl file defining some bindings I'm using in my Groovy script. In addition, I'd like to use the #TypeChecked annotation on my methods to get some guarantees about built code.
My jenkins.gdsl file looks like:
contributor(context(scope: scriptScope())) {
// some definitions
}
And then my script.groovy looks like:
#TypeChecked(extensions='jenkins.gdsl')
void doStuff() {
// ...
}
IntelliJ IDEA autocomplete works, but when building my project I get an error in my jenkins.gdsl file:
Error:Groovyc: groovy.lang.MissingMethodException: No signature of method: org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport.scriptScope() is applicable for argument types: () values: []
Removing (extensions='jenkins.gdsl') gets rid of this error, but then I lose my GDSL definitions when building, so that's a no-go.
It feels like the solution would involve bringing in IntelliJ's standardDsls. I am not at all sure how to do this, or whether it is in fact the correct approach.
#TypeChecked is a Groovy compiler annotation that can run some code during compilation.
But gdsl is an IntelliJ IDEA-specific script that's used only by the IDE to provide some completion and other coding assistance. It doesn't have anything in common with the compiler, and neither of those know anything of each other. So you can remove the extensions value, as it won't provide any typechecking during compilation.
I'm wondering if there is a way to let IDE suggest methods before variables?
When writing code like this it's a pain to select methods yourself (builder class example)
Variable example:
var message = "message"
private set
Thank you
Sorry, it appears you can't reconfigure the IDE or Kotlin plugin in this way. You can file a feature suggestion for Kotlin plugin, but I believe there are cases when variables are preferred over same-named methods, so just reordering them would break someone else's habits, so it's tricky.
You can consider making the variables private (so they won't be shown in the completion list at all) or selecting them and then typing an opening parenthesis manually.
The official site of Typescript get me ask a question,
"Do we need to use namespace or not?".
The following quote explains the 2 things well:
It’s important to note that in TypeScript 1.5, the nomenclature has
changed. “Internal modules” are now “namespaces”. “External modules”
are now simply “modules”, as to align with ECMAScript 2015’s
terminology, (namely that module X { is equivalent to the
now-preferred namespace X {).
So, they suggest that TS team prefer namespace.
Further, it says we should use "namespace" to struct the internal module:
This post outlines the various ways to organize your code using
namespaces (previously “internal modules”) in TypeScript. As we
alluded in our note about terminology, “internal modules” are now
referred to as “namespaces”. Additionally, anywhere the module keyword
was used when declaring an internal module, the namespace keyword can
and should be used instead. This avoids confusing new users by
overloading them with similarly named terms.
The above quote is all from the Namespace section, and yes, it says again, but in a internal secnario.
but in the module section, one paragraph, says that:
Starting with ECMAScript 2015, modules are native part of the
language, and should be supported by all compliant engine
implementations. Thus, for new projects modules would be the
recommended code organization mechanism.
Does it mean that I don't need to bother with namespace, use module all along is the suggested way to develop?
Does it mean that I don't need to bother with namespace, use module all along is the suggested way to develop?
I wouldn't put it exactly that way... here's another paraphrase of what has happened. One upon a time, there were two terms used in Typescript
"external modules" - this was the TS analog to what the JS community called AMD (e.g. RequireJS) or CommonJS (e.g. NodeJS) modules. This was optional, for some people who write browser-based code only, they don't always bother with this, especially if they use globals to communicate across files.
"internal modules" - this is a hierarchical way of organising your variables/functions so that not everything is global. The same pattern exists in JS, it's when people organise their variables into objects/nested objects rather than having them all global.
Along came Ecmascript 2015 (a.k.a. ES6), which added a new formal, standard format that belonged in the "external modules" category. Because of this change, Typescript wanted to change the terminology to match the new Javascript standard (being that it likes to be a superset of Javascript, and tries its best to avoid confusion for users coming from Javascript). Thus, the switch of "external modules" being simplified to just "modules", and "internal modules" being renamed to "namespaces".
The quote you found here:
Starting with ECMAScript 2015, modules are native part of the language, and should be supported by all compliant engine implementations. Thus, for new projects modules would be the recommended code organization mechanism.
Is likely alluding to guidance for users who were not yet using (external) modules. To at least consider using it now. However, support for ES6 modules is still incomplete in that browsers as of May 2016 don't have built-in module loaders. So, you either have to add a polyfill (which handles it at runtime) like RequireJS or SystemJS, or a bundler (like browserify or webpack) that handles it at build time (before you deploy to your website).
So, would you ever use both modules (formerly "external modules") and namespaces? Absolutely - I use them both frequently in my codebases. I use (external) modules to organise my code files.
Namespaces in Typescript are extremely useful. Specifically, I use namespace declaration merging as a typesafe way to add extra properties to function objects themselves (a pattern often used in JS). In addition, while namespaces are a lot like regular object variables, you can hang subtypes (nested interfaces, classes, enums, etc.) off of their names.
Here is an example of a function with a property (very common in NodeJS libs):
function someUsefulFunction() {
// asynchronous version
return ...; // some promise
}
namespace someUsefulFunction {
export function sync() {
// synchronous version
}
}
This allows for consumers to do this common NodeJS pattern:
// asynchronous consumer
someUsefulFunction()
.then(() => {
// ...
});
// synchronous consumer
someUsefulFunction.sync();
Similarly, say you have an API that takes in an options object. If that options type is specific to that API,
function myFunc(options?: myFunc.Options) {
// ...
}
namespace myFunc {
export interface Options {
opt1?: number;
opt2?: boolean;
opt3?: string;
}
}
In that case, you don't have to pollute a larger namespace (say whole module scope) with the type declaration for the options.
Hope this helps!
I'm trying to clear something up that I'm not getting from the dojo docs.
When I create a dojo provide I assume this is like creating a namespace with objects. For example.
myApp = { container: {} }
Written in dojo provide would be:
dojo.provide('myApp.container');
Now I have read somewhere where this is a global. Not sure I get that as its a namespace or are people true in saying this.
Another issue I'm having is if I use a declare to create a class do I need to use provide to create that namespace for me. for example
myClass.js file
dojo.provide('myApp.myClass');
dojo.declare("myApp.myClass", null, {
constructor: function(){
console.log("myApp.myClass created");
}
});
Now if there is truth to provide causing global variables then would this not be a global class now.
When I do a console.log from my app.js file which is my main.js file its not showing as a global but in fact as namespace myApp.myClass.
So can someone clear this up as its a little strange if there is truth in it.
Firstly, to clarify the term "global", technically myApp is a global - it is a variable on the browser's window object. While yes, ultimately the object/class your module defines is contained within that global object (and thus "namespaced" under it), that top level namespace itself manifests as a global variable; it is accessible to any script in the page/app.
Now, onto the declare question. Assuming this code is going into its own module to be loaded via dojo.require, yes, you still need the dojo.provide. While one purpose of dojo.provide is to ensure the variable you will be populating (e.g. myApp.MyClass) and any parent namespaces exist up-front, its other purpose is basically to act like an ACK to dojo.require's SYN - i.e., "yes, you asked for myApp.MyClass, and that's who I am." I'm pretty sure you would find that in the absence of that dojo.provide, dojo.require("myApp.MyClass") would fail, thinking it never found the module it was looking for.
Hope that answers your questions.