We Keep Coding

When making a javascript library, where is a good place to document the API? [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 4 years ago.
Improve this question
I am making a library to generate some custom content. It is pretty verbose, about 1100 lines of code. Although the code is very readable and follows strict naming conventions, I am unsure where to document the API available when including the script file. When including the script in a page, intellisense does not pick up the "public" methods, nor does it for jQuery. jQuery has an awesome website for their API ( http://api.jquery.com/ ), but I do not feel inclined to make something as awesome as that.
Where should I document this custom API?
If in comments, what structure of comments would you suggest?
Edit
My point for intellisense was that even good naming conventions are going to require documented API. So I am definitely interested in a generic approach.

I think jsdoc is pretty popular.
http://code.google.com/p/jsdoc-toolkit/
You would document inline, following the conventions on the link. You would distribute a minified/obfuscated production build for deployment, and the documented one for development (i.e. you could do that)
Edit, you could also find more options here: http://o2js.com/2011/05/01/how-to-document-a-javascript-framework/

It's not generic, but if you didn't mind maintaining separate versions for different editors, Visual Studio's IntelliSense will load and parse XML comments in your JavaScript code. I would suppose MonoDevelop and SharpDevelop could use the same file as well, but I don't think IDEs like IntelliJ or Eclipse would get any use out of it...
HTH.

it depends how complex your api is, for my own small libraries i just make a big comment at the top of the file that contains
a quick writeup of what this is all about
if the library operates on html markup some example code that can be copy&pasted
a list of the functions with their parameters and one-line documentation for each
examples of how the library is typically used
notes/warnings/limitations. there's always something weird going on people won't expect
basically this is what you'd put in a C header file.
i guess you could do all the things i mentioned above in a separate file and then use markdown syntax (i'm too lazy ... also i prefer having everything in a single file).
p.s. some people mention inline-comments (i.e. directly where the functions are).
this is of course an option too. but to me it seems this is convenient only if have the docs auto-generated, it is a horrible way to quickly study the documentation inside the file because it lacks a big picture view.

Generate jQuery like API-Documentation (not from sourcecode!) [closed]

Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
I am currently writing a plugin for jQuery.
Now I wonder how I should create the documentation for this plugin as I guess that there are better ways than directly writing HTML.
However, I do not want to put my documentation into the sourcecode and thereby making finding the correct lines while debugging impossible. Thus, I am looking for a way to separate documentation and sourcecode.
How is the jQuery documentation generated? When looking into the jQuery sourcecode, I don't find any documentation annotations which makes me hope that I might be able to use the same system as they do.
Are the tools they use somehow documented?
I found the following XML-file while looking for an answer http://api.jquery.com/api/ which seems to be generated sometime inside the "build"-process of jQuery.
I would be happy to write my documentation into a similar file and run some tools over it to "prettify" it for displaying it to the user.
How do you create your documentation for jQuery libaries (except putting it into the sourcecode)?
Does anyone know the tools the jQuery team uses (or at least in which format the documentation originally is)?
Many thanks in advance!

It looks like NaturalDocs provides for documentation in external files (as well as in the source code).
The tool that the Prototype team use for documenting Prototype, PDoc, works purely from comments. (The link died, so I removed it.) So you could have .js files that were purely the PDoc comments for your plug-in. 2015: As far as I can tell, PDoc is dead.
I'd advocate having the comments in the source code — classic maintenance issue having them separated — but if you're set on not doing that, fair 'nuff, both of those seem to be options for you.

While I do not agree that adding documentation to source code can make it harder to find the correct lines during debug, I appreciate the sentiment that certain styles of documentation can be verbose and a bit of an eye sore while trying to just "get into the code."
I really like the approach taken by the folks behind underscore.js and backbone.js in their 'annotated source' documentation.
For example, check out the underscore annotated source here. This documentation was generated based in-line comments, as seen in their source on GitHub. But notice this is not the heavy, multi-line documentation style favoring verbosity over brevity. I realize you asked for out-of-file documentation, but I submit this to you as a potential solution to your problem.
You can generate this type of documentation with Docco, which also includes links to Ruby, Python, and even shell script implementations.

have you looked into jsdoc?
JsDoc Toolkit is an application,
written in JavaScript, for
automatically generating
template-formatted, multi-page HTML
(or XML, JSON, or any other
text-based) documentation from
commented JavaScript source code.

Is there a free/open-source JavaScript-to-JavaScript compacting compiler (like Google's)? [closed]

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
If you look at the source of Google pages with JavaScript, you'll find that the JavaScript is clearly not readable -- or maintainable. For example, all variables and functions are one-letter named (at least, the first 26 are...); there are no extraneous white-spaces or linebreaks; there are no comments; and so on.
The benefits of this compiler are clear: pages load faster, JavaScript execution is faster, and as a bonus, competitors will have a hard time understanding your obfuscated code.
Clearly, Google is using some sort of a JavaScript-to-JavaScript compacting compiler. I am wondering if what they're using is an in-house tool? If not, what are they using? Are there any publicly available (ideally, free/open-source) tools of that sort?

YUI Compressor is a Java app that will compact and obfuscate your Javascript code. It is a Java app that you run from the command line (and would probably be part of a build process).
Another one is PHP Minify, which does a similar thing.

Another one is ShrinkSafe that is part of Dojo but may be used stand-alone (either in a build script, command line or at the website):
http://shrinksafe.dojotoolkit.org/

You may be looking for GWT - it's Java-to-JavaScript rather than JavaScript-to-JavaScript, but you may still find it useful.
I can't comment on what internal tool, if any, we use for JavaScript-to-JavaScript. (To be honest, I don't even know offhand... I'd have to look it up before explicitly not telling anyone :)

It's actually pretty unlikely to be JS->JS, much more so to be Java->JS. These days I believe the recommended JS compressor (for this is what they're called) is the YUI compressor, but others like /packer/ exist

Crockford.com's JSMin is one step in that direction, assuming you're only looking for minimization and not obfuscation.

Python library for rendering HTML and javascript [closed]

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 6 years ago.
Improve this question
Is there any python module for rendering a HTML page with javascript and get back a DOM object?
I want to parse a page which generates almost all of its content using javascript.

The big complication here is emulating the full browser environment outside of a browser. You can use stand alone javascript interpreters like Rhino and SpiderMonkey to run javascript code but they don't provide a complete browser like environment to full render a web page.
If I needed to solve a problem like this I would first look at how the javascript is rendering the page, it's quite possible it's fetching data via AJAX and using that to render the page. I could then use python libraries like simplejson and httplib2 to directly fetch the data and use that, negating the need to access the DOM object. However, that's only one possible situation, I don't know the exact problem you are solving.
Other options include the selenium one mentioned by Łukasz, some kind of webkit embedded craziness, some kind of IE win32 scripting craziness or, finally, a pyxpcom based solution (with added craziness). All these have the drawback of requiring pretty much a fully running web browser for python to play with, which might not be an option depending on your environment.

You can probably use python-webkit for it. Requires a running glib and GTK, but that's probably less problematic than wrapping the parts of webkit without glib.
I don't know if it does everything you need, but I guess you should give it a try.

What JavaScript Repository should I use? [closed]

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
Many languages have standard repositories where people donate useful libraries that they want others to have access to. For instance Perl has CPAN, PHP has PEAR, Ruby has RubyGems, and so on. What is the best option for JavaScript?
I ask because a few months ago I ported Statistics::Distributions from Perl to JavaScript. (When I say ported I mean, "Ran text substitutions, fixed a few things by hand." I did not rewrite it.) Since I've used this module a number of times in Perl, I figure that statistics-distributions.js is likely to be useful to someone. So I've put it under the same open source license as the original (your choice of the GPL or the Artistic License). But I have no idea where to put it so that people who might want it are likely to find it.
It doesn't fit into any sort of framework. It is just a standalone library that gives you the ability to calculate a number of useful statistics distributions to 5 digits of accuracy. In JavaScript.

JSAN (JavaScript Archive Network) sounds like the kind of thing you're looking for, but I've never personally used anything from it apart from Test.Builder.
As long as your JavaScript can be dropped in to people's projects without polluting the global namespace or doing things which are liable to cause breakage in other people's code (adding to Object.prototype, for example) I would just stick it somewhere like Google Code as already suggested.

There is no centralized repository for JavaScript. JS Libraries usually have their own plugin-repositories, but for stand-alone scripts, The best way to promote it is to send it to famous website such as ajaxian or mashable

AFAIK, there is no central JavaScript repository, but you might have success promoting it on Snipplr or as a project on Google Code.

You could start a project on SourceForge to contain useful snippets of code like this (or google for snippets to find one).

Perl, Ruby, PHP, etc all have distribution mechanisms built into the language to consume such libraries.
There's not such a thing built into JS.
There are tons of script archives out there - but no "central" JS repo.

Consider packaging it up as a plugin for one of the major Javascript libraries such as jQuery - see http://docs.jquery.com/Plugins/Authoring for more details. This way it can be included on their plugin page which will get it good exposure as they have a huge developer base and it'll be one of their first ports of call when a need arises for such functionality.
Whilst jQuery is one of the most popular frameworks (if not the most) out there, there are a host if other libraries you could consider using in addition to/instead of it.