JavaScript documentation needed

Jaza - June 28, 2005 - 05:07
Project:API
Version:HEAD
Component:Code
Category:feature request
Priority:normal
Assigned:Unassigned
Status:active
Description

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

drumm - September 4, 2006 - 01:05

We actually maintain our own parser. What would the comment format look like?

#2

jvandervort - September 8, 2006 - 20:48

"...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

agentrickard - May 22, 2007 - 15:16

If nothing else, we can view source of the js files if we make parser.inc read js files as HTML. Same for css.

<?php
 
if (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

drumm - September 30, 2007 - 02:34

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

Rob Loach - October 23, 2007 - 13:53

Subscribing.... I'd really like the Javascript documentation to be available.

#6

beginner - January 1, 2008 - 09:37

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

moshe weitzman - January 4, 2008 - 16:28

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

gabriel. - June 5, 2008 - 08:56

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

luisrojas500 - July 30, 2008 - 14:24

hola me interesaria saber si pueden traducir toda esta informacion al español por que estoy cansado de traducirla yo en google ok

#10

luisrojas500 - July 30, 2008 - 14:25

<?php
echo "Este texto me da error me pueden ayudar";
?>

#11

drumm - August 26, 2008 - 08:41

This will be made possible with http://drupal.org/node/300031.

#12

caktux - April 26, 2009 - 08:55

#13

caktux - April 26, 2009 - 09:18

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

Carl Johan - September 4, 2009 - 11:56

+1

 
 

Drupal is a registered trademark of Dries Buytaert.