JavaScript documentation needed
| Project: | API |
| Version: | HEAD |
| Component: | Code |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | active |
Jump to:
I was browsing around drupaldocs.org, and I noticed that the newly added JavaScript code is not documented on this site. Drupal CVS (HEAD) now has three JavaScript files - autocomplete.js, collapse.js, and drupal.js - and all up this means that there are 28 JS functions in Drupal core. The AJAX functions make up most of this code, but more recently the collapsible elements functions were added, and no doubt the number of JS functions is only going to get bigger from here on.
I understand that although Doxygen doesn't support JavaScript natively, there is a utility available (a perl script) that allows JavaScript to be parsed by Doxygen:
http://www.stack.nl/~dimitri/doxygen/helpers.html
How hard would it be to get the API module to support JavaScript? We really need to get those JavaScript functions documented in the drupaldocs.org API reference. 28 functions is a lot of undocumented code in Drupal core. I guess this isn't a huge worry for now, seeing that the JS is only in HEAD. But when Drupal 4.7 is eventually released - and although it seems like it's ages away, it's really not that far off - this really should be done.
#1
We actually maintain our own parser. What would the comment format look like?
#2
"...and all up this means that there are 28 JS functions in Drupal core."
Not even counting the new jQuery functionality and the changes from 4.7 to 5.0.
It's like wading through a dark forest...
#3
If nothing else, we can view source of the js files if we make parser.inc read js files as HTML. Same for css.
<?phpif (preg_match('!\.(htm|html|js|css)$!', $file_name)) {
print('Parsing "'. $file_path .'"...<br />');
api_parse_html_file($file_path, $branch_name, $file_name);
return TRUE;
}
?>
Then we could write a new parser element later....
#4
I reviewed a patch which added js. The result was shredded javascript.
A blank type, which does not shred the code, could be made as a starting point.
#5
Subscribing.... I'd really like the Javascript documentation to be available.
#6
A parser would be nice, but much can/should be done beside this.
What is also missing:
1- better in-code documentation. drupal.js had good documentation, but collapse.js and most other core .js files are much more sparse. -> individual patches could be filed for each .js file to document them better.
2- a start-up guide is needed to explain how to use those functions, just like the FAPI start-up guide that was written for D4.7.
I am adding the sources I know about in the API section of the handbook:
http://drupal.org/node/205296
#7
i think a parser and integration into api module is essential. the difference between pre api.drupal.org and post api.drupal.org is enormous. javascript in drupal will benefit enormously from doing same.
#8
Has anyone taken a look at JsDoc toolkit (or, previously, JSDoc)? The documentation syntax is almost exactly the same as doxygen. I think it'd be a good choice (licence issues aside).
If anything, this definitely provides a good starting point I think.
#9
hola me interesaria saber si pueden traducir toda esta informacion al español por que estoy cansado de traducirla yo en google ok
#10
<?phpecho "Este texto me da error me pueden ayudar";
?>
#11
This will be made possible with http://drupal.org/node/300031.
#12
See also #445130: Namespace the Drupal jQuery functions for 7.x-dev
#13
To have a little follow-up from a discussion with quicksketch on IRC, making the api module parse js files would be an option. Would that be related to #300031: Rework PHP parser ?
#14
+1