Hi,
This is the last week for the Google Summer of Code, and we are supposed to be documenting our code changes. The coding guidelines on the phpMyAdmin Wiki say that the comment syntax must be JSDoc compatible.
As JSDoc is no longer maintained, I downloaded JSDoc-Toolkit, and tried running it on some of my jQuery and JavaScript code. The toolkit could correctly parse all the functions written in JavaScript, but it could not document the jQuery procedural code. I searched on the net, but could not see any examples of jQuery code being documented with this toolkit. There are examples of jQuery plugins and functions being documented with JSDoc-Toolkit, but could not find anything for simple jQuery scripts.
Has anyone seen JSDoc working with jQuery? (or for that matter, any other JavaScript library. We could learn from how it was implemented for them.) I discussed this issue with Ankit today, but even he was trying to figure out how to do this. If there is no such example available, how do we proceed for this week, before we submit our code samples to Google? The comments will be part of my code, whether the toolkit can parse them or not.
Hi,
I think, jQuery must not be documented. But your own functions wich uses jQuery. You can use (like phpDocumentor too) link tags to the original jQuery documentation.
jQuery uses it's own coding style, cause it's to large (thousand lines of code, many plugins). It's to much to change jQuery into a JSDoc format.
Regards Michael
Am 12.08.2010 21:35, schrieb Ninad Pundalik:
Hi,
This is the last week for the Google Summer of Code, and we are supposed to be documenting our code changes. The coding guidelines on the phpMyAdmin Wiki say that the comment syntax must be JSDoc compatible.
As JSDoc is no longer maintained, I downloaded JSDoc-Toolkit, and tried running it on some of my jQuery and JavaScript code. The toolkit could correctly parse all the functions written in JavaScript, but it could not document the jQuery procedural code. I searched on the net, but could not see any examples of jQuery code being documented with this toolkit. There are examples of jQuery plugins and functions being documented with JSDoc-Toolkit, but could not find anything for simple jQuery scripts.
Has anyone seen JSDoc working with jQuery? (or for that matter, any other JavaScript library. We could learn from how it was implemented for them.) I discussed this issue with Ankit today, but even he was trying to figure out how to do this. If there is no such example available, how do we proceed for this week, before we submit our code samples to Google? The comments will be part of my code, whether the toolkit can parse them or not.
Hi Michael,
On 13/08/2010, Michael Keck sfnet@michaelkeck.de wrote:
Hi,
I think, jQuery must not be documented. But your own functions wich uses jQuery.
I guess I was not clear enough in my mail. Documenting jQuery (jquery.js and jquery-ui.js) was not what I meant. I was trying to get JSDoc to pick up comments from javascript files like sql.js, which contain very few named functions, and mostly anonymous functions that are attached as handlers for various events (click/ready/submit). I'm experimenting with a combination of @name, @function and some other tags to see if I can get them in the documentation, will get back to the list with results when I have them. :)
You can use (like phpDocumentor too) link tags to the original jQuery documentation.
If I've understood the JSDoc documentation correctly, this would have to be done with the @see tag, as the @link tag is meant only to link to a documented symbol and jQuery's methods are not part of the documentation that we would generate.
Looks like I'm having some success by using @namespace, @memberOf, @fieldOf and @lends. JSDoc-Toolkit can now parse the anonymous functions and the variables in the jQuery scope. However, the output can be better, so I'll carry on experimenting with it and push the working documentation comments to the repository.
Ninad S. Pundalik
-
Michael Keck -
Ninad Pundalik