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.
Related
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 5 years ago.
Improve this question
Background
I just finished a small HTML5 project in cloud9 IDE. My project is composed of an index.html file, 3 JavaScript files, and a custom styles.css file.
I know I cannot document HTML and CSS, but since the core of my project is the JavaScript within it, I would like to document it.
Research
For this reason, I searched on how to use JavaScript documentation generator tools like JSDocs, Docco, Dox and Esdoc. I also read articles on the matter (comparison between JavaScript documentation tools) and I even gave a look at Naturaldocs.
Problem
The main problem here, is that (as far as I understand) these tools (with the exception of Naturaldocs) all produce beautiful HTML and Markdown pages based on the documentation that my files already have. They read the comments I added and then they generate a document based on it.
This is not what I am looking for.
What do I need?
I am looking for something like the comment feature of the pluggins Ghostdoc and Atomineer where you press a combination of keys and the pluggin documents your entire document with boilerplate code, saving you from that hassle.
Final notes
I installed all the previous tools (except Naturaldocs) using npm. Perhaps I missed something, but I didn't find any tool that does what Ghostdoc and Atomineer do, and I can't install any of these pluggins in the ACE editor that cloud9-ide uses (afaik).
TL;DR
Does anyone know of a way to document JavaScript files in the Cloud9 IDE?
Unfortunately, after researching, I concluded that there is no tool to automatically generate documentation based on JavaScript code. You have to document everything manually, and then pick one of the many existing tools to generate an HTML page or something similar.
I ended up using JSDoc, since its documentation standards are easily accessible and relatively well documented.
Hope this helps someone else coming from the same background I came from.
Additionally, I also created a feature request on the official forums:
https://community.c9.io/t/javascript-documentation-generator-cloud9-ide/5918
Hopefully someone will see it and make something out of it.
there is no plugin for ace, but there are cli tools like http://smartcomments.github.io/, you could use it on cloud9 too.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
I know that this is more of a legal question but I thought I'd give this a shot.
I am learning javascript and I found some interesting drop down menu's on a webpage. I wanted to learn more about them but the code is minified with the following in the comments above the minified code:
// Unauthorized decryption/reproduction of any codes contained herein is strictly prohibited and will result in severe civil and criminal penalties.
Is it really illegal for me to unpack the code and look through it? Can I be sued for looking at code without actually using it?
I'm no expert, but if there were anything criminal about viewing a website's source code, then browsers would not make it so easy.
While I can definitely say that using someone else's code without permission is wrong, I think it's a great thing to learn from it.
IANAL
Minification is not encryption. You already have permission to copy the file to your machine and open it (as your browser requires these permissions to use it). There is no legal protection for examining the contents of a file that's freely available. You can even modify it on your own system at will, these sorts of copyright allowances fall under fair use because you're doing so for educational purposes.
What you can't do is distribute the file or the modified file.
In my honest opinion, it shouldn't (and probably isn't) illegal to look at the code since it's open to anyone.
Using and learning from the source code are two completely different things.
Using someone's work without their permission is simply wrong no matter what the context is (code, images, art, etc).
But learning from other source code is probably the best way to learn and get better.
As for their legal note, I think they just put that there to scare people off but I don't think it would stand in court.
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 5 years ago.
Improve this question
I'm looking for a library in scala that generates JavaScript from an abstract syntax tree.
I want to use it in an compiler that generates JavaScript at the end and I don't want to implement the pretty printing part myself.
I spent half of yesterday researching this. It seems there is no standard, standalone solution. Every project I looked at rolled their own:
Scala-JS: The JavaScript AST classes in Sébastien Doeraene's Scala-JS project are here: https://github.com/sjrd/scala-js/blob/master/compiler/src/main/scala/scala/tools/nsc/backend/js/JSTrees.scala and the conversion to strings is here: https://github.com/sjrd/scala-js/blob/master/compiler/src/main/scala/scala/tools/nsc/backend/js/JSPrinters.scala
JScala: The JavaScript AST classes in Alexander Nemish's JScala project are here: https://github.com/nau/jscala/blob/master/jscala/src/main/scala/org/jscala/model.scala and the conversion to strings is here: https://github.com/nau/jscala/blob/master/jscala/src/main/scala/org/jscala/JavascriptPrinter.scala
s2js: The JavaScript AST classes in Alvaro Carrasco's s2js project are here: https://github.com/alvaroc1/s2js/blob/master/plugin/src/main/scala/com/gravitydev/s2js/Trees.scala and the conversion to strings is here: https://github.com/alvaroc1/s2js/blob/master/plugin/src/main/scala/com/gravitydev/s2js/JsPrinter.scala
Lift (see #thoredge's answer) combines AST classes with string generation in a single file, here: https://github.com/lift/framework/blob/master/web/webkit/src/main/scala/net/liftweb/http/js/JsCommands.scala
How standalone and reusable might these various classes be? Just giving the code a visual onceover, it appears to me that the AST classes in JScala and s2js are standalone and could easily be borrowed by another project. The Scala-JS AST classes seem somewhat more entangled with their surroundings; Lift, even more so. (I welcome edits that improve on my informal impressions.)
How mature and battle-tested are these various projects? My informal impression is that they rank in descending order as follows: Lift, Scala-JS, JScala, s2js.
For my own project, I think I'm going to copy-and-paste the two source files from JScala and see how it goes.
P.S. I also mention, for completeness' sake:
js-scala generates JavaScript strings directly from Scala ASTs, rather than going through intermediate JavaScript ASTs. (See for example https://github.com/js-scala/js-scala/blob/master/core/src/main/scala/scala/js/gen/js/Compile.scala) There is a very good blog post comparing js-scala and scala.js here.
I didn't look at Scala-GWT.
The Lift web framework generates JavaScript from an AST. However, I've never looked at the generation end of it. The AST is described loosely here http://exploring.liftweb.net/master/index-10.html
StringTemplate (from ANTLR) is pretty nice for code generation, I'd say, and it does track indentation and keeps indenting nested statements at the right level. Not really pretty printing, but better than nothing. (At the same time, I wonder why you want pretty printed JavaScript, if in the end it's going to be minified anyway.)
There is a Scala wrapper for StringTemplate (at least one, I seem to recall I saw more): http://software.clapper.org/scalasti/
Virtualized-scala doesn't seem to be what you need, I'd say, since that starts with Scala a Scala AST, and that's not what you seem to have.
However, if you're interested in those sort of things as well, you might want to check http://nescala.org/2013/talks#26 (by Alvaro Carrasco) as well.
There is the Virtualized-Scala project, one of its instances is generating Javascript from Scala code, js-scala. There you will find links for projects and talks about it.
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.
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 1 year ago.
Improve this question
I have a lot of customized javascript and layout design, and I want to prevent people from using those. Is there any practical way to do this, or do I basically just have to be happy my php code does not show? I want to at least make it difficult to copy my site.
If people really want to get access to your source code they can do that fairly easily.
It is possible to slow people down to a limited degree by obfuscating code.
See:
http://code.google.com/p/minify/
http://refresh-sf.com/yui/
http://ajaxian.com/archives/utility-javascript-obfuscator
Maintaining obfuscated code is difficult. What you want to do is obfuscate it before deployment so that you can test and debug with the normal version. Debugging problems on a live site can be made a lot more difficult by the obfuscation.
All client-side code can be copied. If you're a web designer, your best bet is to just brand yourself well and keep innovating so that clients are more interested in the originator than the imitator.
There's no way to prevent people from seeing your source code. There are ways to obfuscate it and make it difficult to reuse, but there's no way to hide it. Also note that obfuscation makes it hard to maintain as well.
By far the most widespread method is to write so bad code that no one in their right mind would want to copy it, it's employed by approx 99% of web sites.
Is it actually a problem to you if someone snatch a piece of your code?
Sure it is a problem if someone the steal the whole site/application, but the only way you can really deal with that anyway is through standard legal means.
I use the Google Closure compiler for javascript. This is to reduce download size and remove redundant code but it has the added benefit of making the code much harder to read.
I have always envied people who sell JavaScript products because their work is always out in the open. I think this is a terrific deterrent for anybody who has something to lose—i.e., businesses, commercial web sites, and such. The day Google (or another big search engine) offers the possibility to search in pages' source code, you can start detecting copyright infringements within minutes.
And even if that search engine option never comes up, it's still possible to find out, very quickly and effortlessly, whether a site uses stolen Javascript.
On the other hand, a minifier used by the person stealing the code would make this much, much harder. So some minification/obfuscation, as suggested in the other answers, is probably a good idea nevertheless.
You can use an obfuscator for your code which will make site loadable but not readable to the other developers - they will not have an easy way to modify and adapt it.
You can use an obfuscator, if you like. It makes the source human-unreadable.
Scare them by using copyright marks in your code and a good lawyer. If they believe that you will sue them maybe the will steal form someone else.