typescript documentation generator - javascript

i am starting documenting my java-script + typescript website with jsDuck
I've documented my class very well , but my problem is interfaces - they don't compile from the ts file over to the java-script.
here is my output, as u can see the page doesn't know who is IComboBoxScope
of course it understandable due to the fact it doesn't generated to the java-script
http://i.stack.imgur.com/PIVKe.jpg
is there a proper way to workaround this in jsDuck?
IF NOT, is there other products or solutions for documenting js with typescript out there?, maaybe jsDoc? ,typeDoc?
sorry for the poor sample/photo, i am working on a private network.

just wanted to share my findings,
i have found a great solution typeDoc is really good, it doesn't need the compiled javascripts, it is dedicated to the ts files,
new solution, active environment and the great thing is that i only need to run a 1 line script with the project library as a parameter.
typedoc --out path/to/documentation/ path/to/typescript/project/
output example
i have seen options to change themes, class hierarchy is working very well
installed by NPM and support es 3,es 5
great!.

From JSDuck side there is no simple workaround as JSDuck has no concept of interfaces. You might document your interfaces as abstract classes for JSDuck, but it's not really the same. You're better off using a tool that natively supports TypeScript.

Related

Intellisense of VS Code is poor

Hi I am using VS Code for quite some while and it's Suggestions of, for Example Class properties or methods is kinda poor. I wanted to check out if this is suppose to be like that or if that is an Issue only for me. I am using it mostly for frontend development with JS/TS or JS Frameworks and often when I install npm packages and import them Intellisense is not showing me their properties which is very lame because this should be in my opinion the number one support it should provide. Many other features of it are great so I would like to keep using it but if that is the supposed behaviour I think I have to switch to a new IDE.
For Example I am using Three JS right now which has in my opinion a very solid Object Oriented Style where it is very essential to know what properties and methods a class has, though Intellisense kind of does not know unless I have typed it once manually, e.g:
I have imported Three JS as follows at the top of the file:
import * as THREE from '../node_modules/three/src/Three.js';
and I am looking for TextureLoader which suppose to be a method of the THREE class which it is when I type it manually, everything works fine though VS Code does not seem to recognize it which is very poor behaviour for an IDE. The Suggestions you see in the Image are the only ones it suggests me. (There is textureLoader typed with a small t at the beginning, but that is because I have used a variable with that name) so VS Code only suggests me things that I have typed already. And
I have checked all the related Posts Stackoverflow is showing me but nothing is related to this topic and All the bug fixes only are related when you have a literal bug in VSCode, but I am not even sure this is an actual bug. Also many people love VSCode and claim it is the best free IDE and I am wondering why if it even can't provide the most fundamental things. I remember Eclipse for Java where it showed you every attribute and method of a class.
I thought it could be a problem of JS since it has no types but I think I remember that Webstorm provided the suggestions correct for JS
So my question is, is that expected? Should the Intellisense mechanism not detect Methods and variables defined in a imported class and just provide you with a list of all of them?
So I have found out that it is not just a problem with my VS Code. VS Code just cannot know what types or methods are available for a class or object. I thought it might have some parsing capabilities running through an class and picking up it's methods to display it in the suggestion/code completion box, but I guess this is to overkill.
So Type completion is available if you use Typescript. For me event though I am using Typescript together with Three.js I still haven't had any useful suggestions in my VSC. So I have found out that the IDE relies on the type definition files "[name].d.ts" where types for Typescript are defined. These should be provided by the author of libraries/ packages you use.
If their are not there is a repo where you can check if such types are available on the npm registry found under #types so for me I had to manually run:
npm install --save-dev #types/three
which installed me a new directory under #types/three with a d.ts for every three JS Module.
when you do then an import like:
import * as THREE from 'three';
typescript knows to also look for declaration files d.ts under "node_modules/#types/three" I guess
So to summarize:
No code completion because of js dynamic type system like [python, ruby]
You can have code completion using typescript since it has static types like [java, #c]
There must a [name].d.ts file provided telling the ide how a class is defined.
For build-in things like the 'dom' and 'window' it is provided by default when installing typescript
correct me if I'm wrong

Static Call Graph analyzer for Javascript

I can't seem to find a basic piece of tooling which is a static analyzer that shows me which pieces of code use methods from which other pieces. I could even do with a very primitive one that only shows me which source files contain references to names found in other files in a NodeJS project (still using CJS require here). So far all I have found is a couple of abandoned projects, but one should think there simply must be something out there.
Edit: Graphical output is not required (but certainly a plus); what I primarily need is a tabulation (text) of which functions in which module call functions from which other modules so I can order dependencies.
Sublime text has this feature where when you hover over a name you get the location where that name was defined; this even works across modules and with CoffeeScript. Does anybody know how that is implemented?
This is an actively maintained proprietary call graph generator that supports multiple languages.
Usage : callGraph <files> <options>
https://github.com/koknat/callGraph
I’ve been looking for a similar tool to help my team track the indirect usage of a deprecated function, so I ended up writing a script based on the ts-morph module: https://gist.github.com/adrienjoly/fc117b187f87cca3417abc4a8433e3a2
It’s a node.js CLI that generates the call tree (a.k.a. call hierarchy, or dependency graph) of a function. You can probably modify it to support JavaScript projects. Or create a tsconfig.Json file that includes your JavaScript files.
Hope this helps!

How to add flow and typescript typings to NPM module

Is there a guide how to add flow and typescript typings to NPM module simultaneously.
I can not find a good guide and it is common problem for open source libraries that in issues people ask for adding typings.
The simple answer, right now seem there are no ready to use solutions.
When you are creating a lib and you are exporting your module with index.js for example you can add index.d.ts and index.js.flow and it will work.
If you already using for you lib types the process of creating definition can be very enoying, luckily there are some good people on it.
Flow already have flow gen-flow-files, still not release under stable.
For typescript, I don't know if there is something similar, but TS more mature I hope they did something.
Now the other painful process, you got one of the definitions you want to convert it to the other one. If you write you definition in TS there are few choices for you to convert it to flow (I don't have any experience with any of them).
But if you writing with flow, I didn't find anything that allows you to covert it to TS.
I have started to create a boilerplate and playground focus on this specific problem.
https://github.com/idanilt/flow_ts_lib
Right now this solution fit my needs, write flow lib and support TS and flow application (I convert flow to TS with very simple regex).
But I want to added to it as many cases as I can, so anybody want to write a lib will not need to face this issue again.

Is there a precompiler for JavaScript like Sass?

Good morning, is there a precompiler solution for JavaScript like Sass for CSS ?
The only features I need are the partials precompiling (to have fewer js files) and the auto-compression of the file.
I googled for Coffeescript but it's not what I'm looking for and because I don't want a different syntax..
If is there a software like Koala for Sass would be appreciated but even from command line (I'm on Windows) is ok, thank you in advance!
PS: with partials I mean:
#import "file.js"
The tool find this and replace it with the content of the file, creating a new file, maybe in another folder specified by me (As I said, like Koala)
Javascript is directly interpreted by your browser so there is no "partials precompiling" stuff.
What you are looking for is a task runner like Gulp or Grunt that can launch a task (amongst others) that will concatenate your files.
Here is a concat task for Gulp
When you say "precompiled" you mean "concatenate and minify", yes they are technically different because the "compiled" code is still in JS, but they are essentially the same thing.
Google has a tool call Closure "Compiler" that is probably what you are looking for.
Found this answer, by Andy Tran, to the question "What are the HTML and JavaScript equivalents of Sass?":
I’m sure there are plenty of options but I’ve only heard of
CoffeeScript, TypeScript, Babel, and LiveScript.
[...]
CoffeeScript does create some shorthand versions of certain things aimed to make it easier to read/write, but in my opinion, I found it just to be more messy.
Babel was the second that I picked up and I immediately loved it. Babel
allows you to write the newer version of EMCAScript (ES6, ES7) but
compiles it to plain old JavaScript to support older versions browsers
and IE that doesn’t support have support for it.
TypeScript and LiveScript, I’m not familiar about. However, I’ve heard a lot of
positive feedback on TypeScripts and everyone been recommending me to
check it out and use it instead of CoffeeScript!
Hope it helps!

Generating Haxe externs for EaselJS

Being new to both JavaScript and Haxe, this may have a simple answer, but I've discovered that Haxe has externs port on GoogleCode for EaselJS, but they are out of date and correspond to an earlier version. I've been able to fix errors as they occur during compile time, but I'm still wary that I didn't catch al the new variables and function names.
My question is: is there a simple way to generate externs for a large JS library like EaselJS?
You might want to take a look at Joshua Granick's work with BuildJS:
http://www.joshuagranick.com/blog/2011/10/14/use-buildjs-to-make-externs-for-haxe-js-automatically/
Basically there's a tool called JSDuck which is supposed to compile documentation for JavaScript libraries, and it can output to JSON. He's used the output from JSON, combined with his "buildjs" library to build haxe externs.
He's used it for Sencha Touch, and I've used it for ExtJS, but both of those are Sencha products and their coding style is known to work with JSDuck. You can give it a go with EaselJS, if it works then BuildJS should generate pretty accurate externs.
Otherwise, you might try find the author of the original EaselJS externs and see if they can provide an update, or give you help creating an accurate update. Most of the haxe developers you can contact easily enough using the mailing list or google groups:
http://groups.google.com/group/haxelang?hl=en
I'm a bit late with the answer but you can find the latest (v0.5.0) externs for EaselJs here:
https://github.com/Fintan/easelhx
I generated them using BuildHx (https://github.com/jgranick/buildhx) which is now able to parse YUIDoc comments and then tested them by porting some of the code samples that accompany the EaselJs source.
Right, I did try and install Joshua's tool, but I'm running into an issue with JSDuck.
In the example you linked to, JSDuck is supposed to have a --json param, but the latest version seems to have deprecated that. I'm trying some others using the config file:
{
"--out": "out",
"--guides": "json",
"--warnings": ["all"],
"--": [
"src/easeljs/"
]}
But that doesn't work. The guides param seems to fail no matter what I try.
Creating the json file gives me this ouput:
C:/Users/mycmp/AppData/Local/Temp/ocr374A.tmp/lib/ruby/gems/1.8/gems/jsduck-3.3.0/lib/jsduck/json_duck.rb:36:in `read': Permission denied - K:/Vault/Haxe/myproj/json (Errno::EACCES)
So I'm not sure what to do next. It'd be great to get this working for lots of libraries.
By the way, I'm using the latest JSDuck and Windows 7.

Categories