@globals

[GoogleCodeExporter]

Hi,

I'd like a means of documenting globals used by a function (or also
relative globals for nested functions (e.g., static or even enclosing
methods which provide a reference to the object (e.g., "that") which get
passed into the nested function)...

Original issue reported on code.google.com by bret...@gmail.com on 28 Aug 2009 at 5:51

[GoogleCodeExporter]

Original comment by micmath on 8 Nov 2009 at 8:23

• Added labels: Type-Enhancement

[GoogleCodeExporter]

globals are a bad idea in general. If you have them in your code and they are 
not Namespaces or Objects, your are probably using a poor coding standard, more 
then likely without even knowing it. In addition to JSDOC-Toolkit, I have been 
using JSLint by  Douglas Crockford and it have turned me from being a mediocre 
JavaScript writer in to a pretty good one. So for me that would be a No Vote on 
a @globals tag.

Original comment by abyss...@gmail.com on 3 Jul 2010 at 2:57

[GoogleCodeExporter]

I'm a (qualified) fan of JSlint as well (see 
http://webreflection.blogspot.com/2010/02/jslint-bad-part.html ), but sometimes 
you need to use a global say from another library (whether in a global 
namespace or not). Also, my meaning in also supporting "relative globals" (not 
sure the proper term for JS) is to document which variables inside a nested 
function drop in and are used by the closure (like the (required) "use" keyword 
documents in PHP 5.3/6: http://php.net/manual/en/functions.anonymous.php ). 
JSLint itself has a means of documenting which globals are expected, but JSLint 
works only at the file level, whereas, I feel it will be useful to have one at 
the method level.

Original comment by bret...@gmail.com on 3 Jul 2010 at 6:29

[GoogleCodeExporter]

I think the idea of a @globals tag is probably too limited, why not a @uses tag 
to indicate all the external variables used within a function?

var guid = 1;

/**
  @constructor
  @uses guid, some.other, and.so.on
 */
function foo() {}

That might be a handy way to communicate dependencies. However I'm pretty sure 
this could already be accomplished by using the "custom tags" feature of JSDoc 
2, and by modifying your template to list those dependencies on the 
constructor's page.

I'll leave that as an exercise for anyone who really needs that feature, and 
ask that you share your customised template back. If there is a lot of general 
interest then I would consider incorporating @uses into JSDoc 3.

Original comment by micmath on 3 Jul 2010 at 7:21

• Changed state: WontFix

[GoogleCodeExporter]

@uses sounds good. My real interest though in my proposals here is on 
establishing common semantic naming conventions across projects. Thanks...

Original comment by bret...@gmail.com on 19 Jul 2010 at 2:31