Develop Reference

What tools or techniques do people use to make Javascript APIs more transparent?

In all the ways I've worked with Javascript, I find that nothing ever satisfies my desire for self-documenting code. I want to be able to see the APIs of modules, functions, "struct" fields, and event payloads within my own code.
I'm curious if any IDEs or transpiled languages help people easily keep their internal API visible? For example, with many languages, often an IDE will give an expandable tree view of packages/modules/classes/functions. Javascript makes this difficult as there are so many ways to code all of these entities.
I find when writing an application in Javascript that after it reaches a certain size, I have to keep jumping between source files to remember these things. Consistent naming, clear coding style, and such good habits only go so far. In a language that has no static typing, very loose rules around function arguments, and passing functions as callbacks, JS code can be hard to scan and immediately see the higher-level structure. It's hard to separate interface from implementation, as all JS code is implementation.
In large projects with many programmers, it makes sense to enforce rules about documenting functions in comments and maybe auto-generate docs. But doing independent development, this is like a lot of manual work just to remind oneself of the architecture and internal API, and likely to be out of date most of the time. I'm not going to look up a function to remember what params it takes, see that it has no docstring comments, add them and rebuild the docs so I can go read them.
TypeScript sounds promising but seems too tied to Microsoft tools. CoffeeScript saves typing and can make for cleaner code, but I don't think it solves the problem of exposing a high-level view of the structure of an application.
WebStorm actually exposes some of what I'm looking for, but I wonder what else exists.
I'm looking for any tips, tools, techniques others use to mitigate this issue.

Managing a large codebase in Node.js

I am about to embark on a Node.js project with a fairly large codebase. I would prefer to keep my code separate from node_modules.
I would ideally like to work with namespaces and folders as I think it would be a nice way to manage things. However, assuming I have read correctly, this would mean that I would have to import any files/"classes" I require using the path to the file which would be quite messy and hard to manage.
What is the defacto method for managing a large amount/ of code for a Node.js project?

My advice is to use a static typed language, since they provide automatic functionality which helps managing large codebases. That could for example be dart, typescript or coffeescript, all being able to produce javascript.
This post explains well the benefits (especially compared to JS):
http://arstechnica.com/information-technology/2014/06/why-do-dynamic-languages-make-it-difficult-to-maintain-large-codebases/
Some of the main problems stated in the linked article:
There is no modularization system; there are no classes, interfaces,
or even namespaces. These elements are in other languages to help
organize large codebases.
The inheritance system—prototype
inheritance—is both weak and poorly understood. It is by no means
obvious how to correctly build prototypes for deep hierarchies (a
captain is a kind of pirate, a pirate is a kind of person, a person is
a kind of thing...) in out-of-the-box JavaScript.
There is no
encapsulation whatsoever; every property of every object is yielded up
to the for-in construct, and is modifiable at will by any part of the
program.
There is no way to annotate any restriction on storage; any
variable may hold any value.
If you started with JS and don't want to abandon your current code base, you could switch to typescript.
Shortly before my JS project reached 5000 lines of code (in about 15 files), I moved it to typescript. It took me about 4 hours to get it back to running.
This post gives some insights from someone movig Node.js to a typescript environment:
http://tech.kinja.com/my-experience-with-typescript-710191610

How to conciliate DRY and Loose Coupling in Javascript Libraries?

I am building my own JS library;
The idea is that the library should be comprised of small, independent modules, and some slightly larger utilities, that serve mainly to iron out browser differences.
I am having trouble getting anything done, because I am not being able to decide between staying dry or being loosely coupled.
An example? Given:
A small library that takes care of generating dom elements from a template
Another one that takes care of duck-typing issues (is_function, is_array...)
And a last one that creates modal boxes. That last one needs:
some type checking
will be creating the modals using only one function from the templating library
My options for the modal box library:
Be 100% dry, and dependant on the two other libraries. But that means if you are a user wanting to download only the modal box lib, you'll have to make with the two others
Allow users to pass an object of options on initiation that would allow them to specify the functions needed; defaulting to the ones of the libraries. This is better, but in practice, it still means, in 90% cases, using the provided libraries, as creating functions with the same signature might be cumbersome. Furthermore, it adds complexity to the modal box code.
Be 100% loose, and reproduce the functions needed in my modal box library; possibly more efficient because more targeted and there is no need to check for edge cases; but: any bug will have to be fixed in two places, and my download size increases.
So I am wasting time oscillating between the two extremes, refactoring a million times and never being satisfied.
I was going for a more generic question, but then I realized it is really pertaining to JS, because of the size & performance concern as well as the widespread usage.
Is there any known pattern to follow in such cases? What's the accepted way to go about this? Any thoughts are welcome.
[edit:]
This is the only article I found that spells out my concerns. Like the article says,
DRY is important, but so are [...] low coupling and high cohesion. [...] You have to take all [principles] into account and weigh their relative value in each situation
I guess I am not able to weigh their value in this situation.

Personally, I've always taken the view that Loose Coupling refers to creating seams in your code. In classical languages, such as Java, this is achieved by creating Interfaces which hide the concrete implementation. This is a powerful concept as it allows developers to 'unpick the seams' in your application and replace the concrete implementations with mocks and test doubles (or indeed, their own implementation). As JavaScript is a dynamic language developers rely on duck-typing instead of Interfaces: as nothing is frozen, every object becomes a seam in your code and can be replaced.
In direct answer to your question I think it pays dividends to always aim to decompose and modularize your code into smaller libraries. Not only do your avoid repeating code (not a good idea for a host of reasons) but you encourage re-use by other developers who only want to re-use parts of your library.
Instead of re-inventing the wheel, why not leverage some of the more popular JavaScript libraries that are out there; for example, underscore.js is a lightweight library which provides a rich toolkit for duck-type checks and Mustache.js may well take care of your templating needs.
Many existing projects already use this approach, for example, Backbone.js depends on underscore.js and jQuery Mobile depends on jQuery. Tools such as RequireJS make it easy to list and resolve your application's javascript dependencies and can even be used to combine all the separate.js files into a single, minified resource.

I like the concept of DRY, but your right it has a couple of problems.
Your end-user-developers will need to know that they need to download the dependencies of components.
Your end-user-developers will need to know that they need to configure the dependencies (i.e. the options to pass in).
To help solve 1. your project website could customise the download on the fly, so the core code is downloaded along with optional components. Like the modernizer download page.
To help solve 2. Rather than allowing users to pass in options, use sensible defaults to detect what parts of your packages have been loaded in the browser and automatically tie them up.
This loose coupling could also give you the great advantage that could also rely on 3rd party frameworks if the user already has them installed. For example selectivizr allows you to use jquery or dojo etc etc depending on what the browser has already loaded.
Perhaps you could use requirejs to help solve dependency management. I get the impression it's not really meant for libraries to use directly, but instead the end-user-developer... but it could be a nice fit.
I realise my answer doesn't answer your question directly, but perhaps it could help balance out some of the negative points of DRY.

How do you manage a big script?

I'm building a JavaScript engine. I used a simple function as a class, added subfunctions, strings... and used prototypes to add other objects...
Everything is fine. The problem now, is that I'm using one class (or main function), because I need it to be so. It's becoming huge, to the point that I can't control it any more and debugging the code is becoming as hard as hell.
I'm a C# developer, who used Visual Studio. I never come across this problem, because I have different files/classes/forms...
I wonder how developers here deal with large JavaScript files. What tools/strategies/techniques do you use to solve this issue.
Thanks

You can still create multiple objects analogous to your classes and objects in C#.
I suggest you go look at some JavaScript frameworks like YUI3 ( http://developer.yahoo.com/yui/3/ )
These provide nice mechanisms for structuring your JavaScript code and behaviours. For example YUI3 provides the Y.extend method to allow you to extend one object from another much like you do in C#. There's a whole suite of other mechanisms you can use in JavaScript that are actually a lot more powerful than what you've learnt in C#.
Go look up prototypal inheritance, and maybe watch some of the videos by Douglas Crockford on the YUI Theater ( http://developer.yahoo.com/yui/theater/ ). All really excellent stuff that'll show you how you can do this sort of thing in JavaScript without the major headache of giant scripts.
To answer you question more specifically, I use the module pattern in YUI3 to allow me to split my code up into mulitple files. It allows a mechanism where you can define modules then use them from other files, while auto-resolving the required dependancies. So you define multiple JavaScript files containing your behaviours and code defining various modules, which can then be 'used' in other files.
YUI().use('my-module', 'my-other-module', function(Y) {
Y.MyModule.doSomething();
Y.MyOtherModule.doSomethingElse();
});
'my-module' and 'my-other-module' can be defined in completely different JS files, which I then tell the YUI loader where to find, and it automatically includes them into my pages.
This is really powerful, and lets you break up your code for maximum reuse and simplicity. Lots of other developers are also putting their code up on the YUI Gallery so you can mix and match behaviours into your projects.

jQuery. It's a great tool to help you write less and better code. It's a simple JS framework/library you link to on every html page. It should be quite simple to learn, and there's a lot of support, manuals, books.

Google created GWT to solve this problem.

JavaScript object browser?

I was recently tasked to document a large JavaScript application I have been maintaining for some time. So I do have a good knowledge of the system.
But due the sheer size of the application, it will probably take a lot of time even with prior knowledge around the code and the source code itself in uncompressed form.
So I'm looking for tools that would help me explore classes and methods and their relationships in JavaScript and if possible, document them along the way, is there one available?
Something like object browser in VS would be nice, but any tools that help me get things done faster will do.
Thanks!

Firebug's DOM tab lets you browse the contents of the global window object, and you can inspect a particular object by entering inspect(whatever) in the command line.
You won't be able to use it to detect relationships unless an instance of one object holds an instance of a related object, but it's a start.
You can also use the Options menu on the DOM tab to restrict what's shown to user-defined functions and properties, which should help reduce clutter.

Take a look at Aptana, they have an outline that can help you to determine what are the objects and somtetimes their relationship.

Firebug + uneval(obj) is a simple trick that is often helpful.

I see a lot of people talking about examining the DOM within Firebug. However, from your question it looks like you want something like jsdoc? just add type and class information through comments and jsdoc generates documentation including class relationships. http://jsdoc.sourceforge.net/
Google has a fork of it with added functionality http://code.google.com/p/jsdoc-toolkit/
UPDATE: It's not a fork, it's a rewrite by the developer that wrote jsdoc originally as a perl script. It aims at being more adaptable so you can use whatever js inheritance/events/properties style you'd like. Another feature is that it lets you modify the templates used to generate the HTML in a much simpler way.

We don't know if this JS application is designed to run in a Web browser...
If yes, as advised, Firebug (a Firefox extension) is excellent at debugging JS and exploring Dom.
On the IE side, you have some tools like IEDocMon, Web Accessibility Toolbar (it does more than its name) or Fiddler (unrelated to your question, but still a good tool to have).

Firebug (Firefox) / Dragonfly (Opera) can help you with viewing objects in realtime
Aptana / JS/UML(Eclipse) can help with relationships of objects

This is an old question, but let me answer it anyway.
Use an IDE. Integrated Development Environments were made for jumping around rapidly among the code. The key features you will exercise during exploration are viewing the file structure or outline, jumping to a declaration or usage, and searching the entire project for all instances of a string. If you are using WebStorm, set up a custom scope for files except generated files and node.js to aid in searching.
Run 'npm la | less' which lists all your dependent modules with one line descriptions. You may have never seen moment.js and never need to read the documentation, but taking the time to read a one line summary of it is worthwhile. If you need more information on a tool than one line summary, search for the term on SlideShare. Slides are faster than ReadTheDocs.
Document a little as you go. I'm a fan of forcing people to use notebooks constantly rather than scratch paper. Also, I find adding a one line comment to each JavaScript file is worthwhile. You want to know what should be in each directory of your project. I also recommend building a glossary of the exact meaning of domain terms in your system, e.g., what does "job" in your system.
Finally, you may need to just fire up the application in a debugger and start stepping through parts of it. Most large projects have accreted worth from programmers of various skill levels and motivations.
You are aiming for a level of "conceptual integrity" (to quote Yourdon) or to "grok" the software (to quote Heinlien). It does take some time, cannot be bypassed, and can be done efficiently.