Create jQuery as API documentation (not from source code!)

Question

I am currently writing a plugin for jQuery.
Now I'm wondering how can I create documentation for this plugin, since I assume there are better ways than writing HTML directly.

However, I do not want to put my documentation in the source code and thus invoke the correct lines when debugging is not possible. So I'm looking for a way to separate the documentation and the source code.

How is jQuery documentation created? Studying jQuery source code, I find no documentation annotations that make me hope that I can use the same system as they are. Are the tools that they use somehow documented?

I found the following XML file, looking for the answer http://api.jquery.com/api/ , which seems to be created sometime inside the “build” jQuery process.
I would be happy to write my documentation to a similar file and run some tools above it to “prefix” it to display it to the user.

How do you create your documentation for jQuery libraries (except for entering it in the source code)?
Does anyone know the tools used by the jQuery team (or at least in what format the source documentation is)?

Thank you very much in advance!

Answer 1

It appears that NaturalDocs contains documentation in external files (as well as in source code).

The tool that the Prototype team uses to document Prototype, PDoc, works exclusively from comments. (The link died, so I deleted it.) That way, you could have .js files that were purely PDoc comments for your plugin. 2015: As far as I can tell, PDoc is dead.

I would recommend having comments in the source code - a classic service question with their separated - but if you are not configured to do this, honest "nuf", both of them seem to be options.

Answer 2

Although I do not agree that adding documentation to the source code can make it difficult to find the correct lines during debugging, I appreciate the opinion that certain styles of documentation can be verbose and slightly hurt the eye when you try to just “enter the code”.

I really like the approach made by the people behind underscore.js and backbone.js in their annotated source documentation.

For example, look here for an annotated underline source . This documentation was created based on inline comments, as shown in the source on GitHub . But note that this is not a heavy multi-line style of documentation conducive to verbosity. I understand that you asked for documentation without documents, but I present 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 a shell script ..

Answer 3

Have you viewed jsdoc ?

JsDoc Toolkit is a JavaScript application for automatically generating template, multi-page HTML code (or XML, JSON, or any other textual) documentation from commented out JavaScript source code.