I need to choose a documentation generator (similar to jdoc in java or rdoc in ruby) for my javascript project that (built with jquery, underscore and backbone)
Candidates:
jsdoc toolkit
pdoc
natural docs
docco
YUI doc
doctool http://jquery.bassistance.de/docTool/docTool.html
other ?
Requirements
should work with jquery, underscore and backbone. that means object-literal methods etc
I really like pdoc but its too centered around prototype, poorly documented, and I don't want to make extra files (sections?) to make it work (not sure about this)
docco is nice but I want structured output (as in menu + class/func structure like jdoc)
must be command line/makefile compatible (not web pastie)
Tips, tricks, tutorials, success stories, advice greatly welcomed.
Why Doesn't jQuery use JSDoc?
I would rate jsduck from Sencha on top. I have used it on many projects. Simple to use
https://github.com/senchalabs/jsduck
A single command will generate docs like this http://docs.sencha.com/touch/2-0/
You could also look at Dox by TJ Holowaychuk; it's a fork of Docco, but adds some jsDoc syntax support. I personally find that jQuery code often lends itself to looser style of inline documentation like Docco, but I'm currently in the same situation of trying to decide what doc system to use.
I am going through the same exercise at the moment, and from what I've seen YUI Doc is the best. I love the fact that you can run it in "server" mode and view the documentation as you write it. Much better than having to execute a build each time you change the documentation. Also, the documentation that is generated is very easy to read and very well organized.
This is new so it may not fit your output requirements, but you might find njsdoc interesting. Unlike most JS documenters it tries to build documentation by executing the code and investigating the stack rather than just parsing the files for annotations.
https://bitbucket.org/nexj/njsdoc
There is DocumentJS*
*I haven't used it and I am not sure how well it will integrate with Backbone.
Related
The Problem
I have JavaScript-like files with extension .gml
I can convert the source to valid JavaScript via magic-string, and can go back the other way using trace-mapping.
I want to leverage Typescript on my .gml files to get strong Intellisense, e.g. by:
Creating a Typescript "program" that acts on the .gml->.js transpiled files and reports issues back; and
Creating a VSCode extension that proxies functionality to the Typescript language server and reverse-source-maps the results back to the editor.
It feels like there should be a relatively straight forward and generalizable approach to this, but my experiments have not worked out. Reference projects are either for much-more-complex scenarios or much simpler ones, and documentation on the matter is very light.
Prior Art
VueJS and Svelte use custom filetypes (.vue and .svelte), which they pre-process into valid Typescript, HTML, and CSS prior to proxying through to those respective language servers.
Their use cases are far more complicated than mine, and their code bases to accomplish this are extensive. I'm hoping to find a much more streamlined approach.
Possible approaches
I've had a little luck following the Svelte approach of creating a Typescript service and hooking up VSCode operations onto it, but this is extremely tedious.
I suspect that there's some possibility of using a Typescript plugin, but as far as I can tell that approach doesn't support using non-js/ts extensions nor source maps.
In any case I know I'll have to do significant work with the to-and-from-sourcemap conversions, but ideally that's the only difficult work I'd need to do.
Questions
Have you seen any examples in the wild of people solving a similar problem, or solved similar problems yourself?
Are there any deep-dive write-ups about this (I've found a few shallow ones)?
Is the plugin approach viable?
What are the possible ways to get non-js/ts extensions recognized by Typescript?
I've recently fallen in love in WebStorm as an IDE for JavaScript development. The problem is, I come from a world of vim and lightweight editors, so I probably can't fully appreciate all the power that comes with IDE. Yes, I've seen the presentations and read the docs, but there's a lot of features and I'm not sure which of them are truly useful.
So, here goes my question: how do you use WebStorm and what do you find most useful? Any power-usage tips? Configuration hacks? Plugins worth mentioning?
I'm not looking for a list of features, I'm looking for a real-world usage examples and impressions.
PS. I work mostly with pure JS + Canvas element and some NodeJS.
Some random thoughts, maybe more later....
In the help, definitely read the Basic Concepts and skim the WebStorm Usage Guidelines for actions that you care about.
Learn to use Ctrl-Shift-A. It allows you to 1uickly find actions you can do by typing part of them. With that you can find anything once you know it exists.
WebStorm's (like IntelliJ) best magic is its code completion and refactoring features, which come from its code parsing and awareness. It figures a lot of stuff out, but you can help it out by making you have good source files. Put the commented versions of the libraries you use in your project so it can use those comments to display in the doc popups (just having them in the directory is all you need).
Be sure to leave the tips on.
Their forums are useful, but if you have a problem or feature request put it right into youtrack.com. They are much more responsive there. You can also vote for the stuff you want added.
And if you haven't seen it yet, there is a VIM plugin which will give you VIM editor keys, called IdeaVim.
Features I find most useful:
Code formatting. WebStorm's formatter is the best I've seen (of course, it still has some subtle bugs).
Built-in HTTP server: http://blog.jetbrains.com/webstorm/2013/03/built-in-server-in-webstorm-6/, How to open/debug current file using built-in Web server in WebStorm?
JsTestDriver integration.
Plugins. You can always find something useful.
I have just been asked to describe the architecture for a large scale dashbaord style project that i will be working on.
I have bever worked on a application of this size and am a bit lost as to what to say.
Could i be pointed in the direction of any articles that may help me get started and hopefully finished.
I have gleaned the following information thus far but i am not really sure that it describes the architecture.
1) Use classes instead of seperate functions and each class or group should be contained within their own JS file
2) Prior to production there should be a compile step where said JS files are compiled and minified
3) Step2 does not have to contain all the files. Jsut the common ones to start
4) Use a classloader to load classes, plugins etc when they are needed. On research could jQuery's getScript function be used for this or even a jQuery plugin loader:
http://api.jquery.com/jQuery.getScript/
http://www.unwrongest.com/projects/lazy/
Am feeling way out of my depth at the mo so any help would be massively appreciated. Be honest, if the above is competely irrelevant then i guess i am in the wrong job :(
Everything you need to know can be found here:
http://addyosmani.com/largescalejavascript/
Create a library of loosely couple components that communicate through an application controller (e.g. event bus).
I would recommend looking at using ExtJS 4 for this. Its APIs and development methodology closely track what you would expect from .NET or Java for developing a large-scale desktop app.
Version four answers all four of your points. It has...
1) A system for defining Java/C#-like classes in Javascript that work almost exactly the way a Java or C# developer would expect.
2) Dynamic resource loading.
3) The ability to create a final product from the SDK which is a neat, compressed version which contains just what you need.
If you are to do this with pure Javascript, ensure you use some reference architecture in the job. What HDave pointed above is really good material. If you want a ready-made reference architecture as a project startup code, have a look at BoilerplateJS:
http://boilerplatejs.org
After some large-scale projects, I have compiled some of the learnings in to this framework. Look at the samples too. Some of the concerns you raised are already addressed in this codebase such as use of OO concepts, minification and optimizations, decoupled moduler design and many more too.
We started a new project and realized that we needed a general purpose javascript library that contains a nice set of string functions, MD5, base64, allows extensions, etc. Also, copying and pasting functions from other libraries doesn't sound very attractive.
So, I guess the question is which javascript library contains the most general purpose functionality out there? or maybe there is a good collection of global functions out there we could use/extend. We know DOM manipulation is covered by many AJAX libraries including JQuery.
*Mind you, we could alternatively extend ExtJS, JQuery, etc. Is that what you guys are doing?
Google Closure Library
It contains (quoted from link):
a large set of reusable UI widgets and controls, and from lower-level utilities for DOM manipulation, server communication, animation, data structures, unit testing, rich-text editing, and more.
It also contains a nice set of string manipulating methods, in goog.string namespace.
Underscore
Underscore is a utility-belt library for JavaScript that provides a lot of the functional programming support that you would expect in Prototype.js
Underscore is intended to go along with other library, like jQuery or prototype.
It's not extensible like jQuery or Google Closure, though.
*Mind you, we could alternatively extend ExtJS, JQuery, etc. Is that what you guys are doing?
Yes, I do and I think most are. A lot of what you describe as a "general purpose library" is covered by Frameworks like JQuery, Prototype or Moo. And short of clipping the webmaster's nails, there's a JQuery plugin for everything that's not already in the core.
Still, I'm interested to see whether any other "general purpose" libraries come up here. There are fields - like string manipulation, as stated in one of the comments to another answer, and advanced date operations - where none of these frameworks is the holy grail AFAIK.
I use the jQuery library and a bunch of plugins. jQuery's plugin directory contains a lot of useful tools. There's also jQuery UI, a set of interactive components and effects, which you can use if you don't want to use a more complex library like ExtJS.
Of course every project is different, and you will probably end up writing some helper functions on your own.
I realize that others are going to say the same, but jQuery truly amazes me every time I learn something new about it.
DOM, CSS, and event manipulation along with easy AJAX, extensibility, and the plethora of existing extensions make jQuery a wonderful tool for web development.
jQuery is incredibly useful for UI manipulation. However, being open source, it contains some less than optimal code. If you start running into performance issues, don't be afraid to delve into the source and see what's going on.
I have been using jQuery for some time now and that seems to handle most of the basic operations I need. It has a healthy library of plug-ins and you can always write your own. It is a very good lightweight js library and even if it doesn't do all that you need it to you it is a good starting point.
I am developing my first ASP.NET MVC application and I beleive that Script# can help me a lot. But it cannot find the resource necessary to support my development.
I could not find The codeplex site;
There is only one manual, which is very good, but it is not enough;
I could find very few tutorials;
I know that Script# was used to develop ASP.NET MVC scripts and that the source of MVC distributes the library.
But it seems that it is used only internally in Microsoft.
Where can I find other resources???
Do you really think that Script# will be continued and new versions will be deployed and it should be used by third-party projetcs ???
Thanks in advance
Don't be afraid of Javascript, it's a beautiful and powerful language. And with frameworks like jQuery, Prototype and Dojo, DOM manipulation and AJAX are greatly simplified and cross-browser issues are mostly history.
About Script#, I agree with this answer by mcintyre321. Last release over a year ago + closed source = no go for me.
UPDATE Jan/2010: there have been new Script# releases since the original writing of this answer. It's still closed-source but the author mentions open sourcing it after 1.0
UPDATE May 2011: Script# is now open source.
In short, my answer is: if you like powerful IDEs that run on Windows, OOD and C#, use ScriptSharp. It is more maintainable and structured, and demonstrably stable enough to use on serious projects. It can also be easily extended, as illustrated below and by other projects.
Since this is yet another Google indexed thread where people refer to Script# and jQuery as mutually exclusive I just wanted to point out some people are merging these two worlds, and in my case unleashing a lot of power by doing so. I'm offering a completely free and reusable library to access jQuery 1.4 from Script# projects, and full source code for the solution that generates it (almost exclusively from jQuery's own API documentation file):
http://www.christophercrooker.com/visual-studio-2010-rc-custom-tool-for-code-generation-and-jquery14-with-intellisense-for-scriptsharp
IMHO Script# fits well for large projects only, with really "rich" web client. Participating in such kind of project, I could only say that Script# helped us much. josephhemingway's remark about strongly typed is 100% true for such case. Also it allowed us to introduce new .NET developers without any JS background quickly. Assuming Nikhil Kothari's plans to open-source it in the summer 2008, we even decompiled (don't tell anybody! it's illegal) it and introduced generics, operators overloads, various bug fixes, etc.
BUT. Then Script# support faded away. Project on CodePlex with discussions and issue tracking was closed (interesting that parts of framework were published there shortly before). No updates, no future plans, no explanations. After such thing I'd consider Script# only after it goes open source to give the community ability to support it. E.g. on CodePlex.
I use Script#, I think it is great. You can use it with any framework, jQuery, dojo whatever, you would however have to wrap the framework, this could be a big job...
It's only benefit as I see it is that it allows you to develop javascript in a strongly typed environment. I think this is a HUGE benefit. I refuse to develop in weakly typed languages as maintenance is a nightmare.
If however you like to work in a weakly typed language then you wont need Script#.
Short answer NO. Wait for TypeScript.
Script# is really cool, but MS decided not to support it at all. The reason for that turns out to be that they were working on a better version of that - TypeScript (http://www.typescriptlang.org/)
It adds support for everything you need in a static language (intellisense, type checking, interfaces, classes etc.), but still looks very much like JS, and more importantly - confirms to the upcoming ECMA Script 6 standard. (unlike Script# or google's Dart)
Like the others have I would recommend some JavaScript (namely jQuery). Should you wish to continue with Script#, Nikhil Kothari's blog may be a good resource for you. http://www.nikhilk.net/ScriptSharpIntro.aspx -- That being said, I think you'll find that you are more productive with jQuery. There is a large database of community written plugins so you wouldn't necessarily have to reinvent the wheel on everything you want to do. jQuery plugins instead of ASP.NET Controls
Wow Val you got generics to work in
it, I'm impressed, was it hard?
Generics support would be great, so
would method and operator overloading.
josephhemingway
The whole point is that ScriptSharp's parser supports full C# 2.0 syntax. The only thing needed is to generate the proper JS. Not much work, considering JS dynamic nature. Generics would act as Java-style ones, i.e. no generation for each closed type argument set, just one class.
Are you sure that it is illegal to
decompile it, I will have to have a
look to see if it is the terms of use.
josephhemingway
Yep, it's illegal. EULA showed in setup clearly mentions that.
A release went out today, so it is good to see that it is still active.
Regardless of the previous lack of updates and that it not been open sourced I would still use it over plain js. You can stop using Script# at any time and more forward with the 'compiled' js if you don't like it.
I agree with you Val though that it really only fits large js based projects. I don't think you would get much benefit out of using it to perform basic page functionality like validate form input etc. It probably wouldn't be worth setting it up.
If however you are heavily using javascript and need to replicate OOP then I think it is a must. Things like refactoring becomes so easy, with plain js I would never refactor because it was just too hard to implement, over time my code became a mess.
Wow Val you got generics to work in it, I'm impressed, was it hard? Generics support would be great, so would method and operator overloading. Are you sure that it is illegal to decompile it, I will have to have a look to see if it is the terms of use.
The other advantage of using ScriptSharp that no one has mentioned is that if you need to interact with C# (using AJAX/REST/SOAP) you can use the same class definitions in both places and be sure that you have the interface defined properly, because it's the same source file! I have tried to use logic in shared source files with minimal success due to the way ScriptSharp's corelib is not 100% compatible with the C# corelib. But it works great for data file definitions.
I am using jQuery. It is really good. But I beleive that It is more confortable to me to work with C#. Even if it is a subset.
Also I would like to add that you certainly should use ScripSharp when you are planning to develop multiplatform projects. For example, at present time I write my image processing library code for .NET, JavaScript (ScriptSharp), Android (Mono) platforms on C#. Also I am planning to port my code on iOS (Mono) and Windows Phone in the future. And I think it's great code reusing and developer time minimization!