Jump to:
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | Code |
| Category: | feature request |
| Priority: | major |
| Assigned: | ericduran |
| Status: | active |
Issue Summary
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.
Comments
#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
#15
http://code.google.com/p/jsdoc-toolkit/ looks like the parser to use.
#16
@drumm If we move forward with jsdoc, what would the path forward be to get that up and running?
#17
The basic idea is use JSDoc's machine-readable output, I think XML, and save it to our DB, with some unit tests. api_update_branch_files() defines what function is used to parse which files.
#18
I'm going to take this on. I also upped it to critical, as I think JS is a big part of the drupal code base.
Are we all still in agreement that jsdoc-toolkit is still the way forward?
#19
Do we have any JS docblock comments in the code base now, and if so, will this parser cover them? Will it let people use basically the same comment doc syntax we are using for PHP?
#20
Actually, that jsdoc-toolkit project looks like it could be defunct, and it is written in JavaScript (it says so anyway), so I'm not sure how that would integrate with the API module. I would think we need a PHP-based parser for the JavaScript code, wouldn't we?
Also, it's MIT license... I'm not sure that's compatible with GPL?
#21
PHP parsing PHP works because it has a token_get_all() built in. For JS, I'd want to follow documentation standards from the JS community, and use the machine-readable output of a common documentation parser.
#22
Ah, I see.
Then only the license question remains... and I'm unclear on how this would be added to the API module -- or is this just an addition to the API site and not the module?
#23
api_update_branch_files() has a list of what functions to use for which file extensions. js would be added and the new function would
That gets JS documentation into the DB and basic pages. UI work is probably needed to make sure the languages happily co-exist.
#24
We'll also have to make a new standards page showing how to document functions and classes in JS I guess, and figure out what to document. They have a good reference to the @tags, but it doesn't really set standards for how to write good docs.
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
Anyway, Eric: THANKS! I'm sure this will be helpful to have on api.drupal.org -- you are right, there is now a LOT of javascript in the repository. It will be interesting to see what the parser does with it as it is, and how we can make good standards for it.
#25
MIT license is GPL-compatible, by the way, at least according to everything I found in a simple Google search (Wikipedia, and the Gnu foundation, etc.)
#26
thanks for all the feedback I now have a path forward.
#27
After doing some investigation I think the native jsdoc-toolkit project requires too much set up work. Mostly because is built on top of Java with rhino.
Instead I'm looking to using a node.js port ( https://github.com/p120ph37/node-jsdoc-toolkit) which works just like the original js toolkit project but requires a lot less set up.
Any comments, objections?
#28
That's too bad that the official and active jsdoc-toolkit project won't work out well.
I have to say, looking at the node-jsdoc-toolkit project web site that it doesn't look very promising. It has almost no activity, no stable release branch, only one issue in the queue, and just 4 little spurts of activity. So I would be skeptical about adopting it -- if it were a Drupal contrib module with that kind of activity, I would probably steer clear of it. On the other hand, it looks like most of its code comes from the base project, so maybe that's not an issue.
Anyway... Does it work? And would we be able to easily maintain it going forward (by pulling from the base project) if the current maintainer abandoned it (which seems like it might be possible)?
Regarding "too much setup work" for the base project... you mean someone who wants to run this would need to install a few other pieces of software, or is it more than that, once you/we have figured out the right configuration and commands?
#29
By "too much setup work" I mean there's a couple of pieces of software that needs to be install. Once they get set up it works smoothly, But I think Rhino is just too much work. The node project is pretty light in the sense that they're just bringing in the base project and replacing the run.js file to make it work with node.js.
I'll look into it more. I'm sure that in future releases they will probably also move to node.js being that it would make sense for the js project. But I'll find out.
As a side note the node js-toolkit project takes less than 1 min to set up (Assuming you have node.js install) and generated all the js docs for core in seconds.
I'll have more detail later, I need to get back to work :)
#30
So... You are saying that for the base toolkit, you have to install a few pieces of software -- that doesn't sound like a huge burden. Because for this alternate one, you also have to install node.js, which I for one don't have by default on Ubuntu... I'm not seeing a huge distinction here, but having not tried either, I'm still open to being convinced. :)
#31
Another note. We have not ("we" referring to "the Drupal Core development group") adopted any standards for documentation of JavaScript code. We need to do that too. So opening up discussion:
#1337022: Adopt JavaScript JSDoc standards
#32
Apparently version 3 of JSDoc is now under development at:
https://github.com/micmath/jsdoc
(thank you ksenzee for pointing this out on the other issue)
EDIT/added: Note that this version of JSDoc apparently includes Rhino, which was cited as a concern of the earlier version above.
#33
Ugh: https://github.com/micmath/jsdoc/blob/master/LICENSE.md
(lots of licenses)
We need to be careful about license...
#34
hmm, v3 might be the way to go then. It looks like they might support both node, and rhino.
#35
Just a +1 on this. This would be so very awesome. Possibly even better than the Git migration. Well, up there at least. :) I happy to test things.
#36
This is really just major not critical.
#37
:-) I guess not.
I've been moving so I've been completely of the grid the last couple of days/weeks. I should start moving on this ticket again some time next week.
#38
fixing branch (we don't use branch master)