search

AaronNGray / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

@exports is missing on the tag reference wiki page. #291

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
What steps will reproduce the problem?
1. Go to the tag reference at http://code.google.com/p/jsdoc-
toolkit/wiki/TagReference
2. Look for "@exports"

---

@exports is missing on the tag reference wiki page.

Original issue reported on code.google.com by Elliott....@gmail.com on 21 May 2010 at 7:50

GoogleCodeExporter commented 9 years ago 
The "Secure Modules" option was a bit of an experiment and I'm not convinced 
anyone got much use out of it. 
The one commonjs compliant library I know of that uses JSDoc is ringojs and 
they don't use JsDoc Toolkit. Do 
you know of another?

On the other hand I am currently writing JsDoc Toolkit version 3, and it will 
itself be commonjs commpliant, so, 
as I am documenting JsDoc Toolkit version 3 in itself, I suddenly have a great 
need of the @exports tag. Modules 
will be deeply supported in version 3.

Original comment by micmath on 23 May 2010 at 4:01

GoogleCodeExporter commented 9 years ago 
When I'm adding to a class (or class prototype) from within its scope...

  (function(){

    this.class_func = function(){
      // ...
    };

    // Other functions...

  }).apply(really_long_namespace.another_long_namespace.ClassObject);

JsDoc can't determine what "this" is.  I had been using @exports as a way to 
fix that, 
which has had mixed results.  In the end I think it's just a bad practice in 
general to 
do what's shown above, and I'll likely refactor those classes, specifying the 
full 
namespace with each function, or by using an object literal, or something along 
those 
lines.

So while it hasn't been the perfect solution, I have found a use for @exports.

Also, thank you for bringing commonjs to my attention.  I had been looking for 
a "de 
facto" JS standard, and that looks like it.

Original comment by Elliott....@gmail.com on 25 May 2010 at 1:53

GoogleCodeExporter commented 9 years ago 
Thanks for the additional information. Your example is interesting, it's not 
something I've seen before. Can I 
ask why you do it that way? Is it just to prevent "really long name" from 
appearing all over your code? I think 
that a compressor, like The YUI Compressor, would be able to shrink 
'really_long_namespace.another_long_namespace.ClassObject' down to 1 byte, but 
would leave 'this' 
untouched, so your technique would actually be slightly harmful to compression 
(if that's something you care 
about).

It's off topic, but as an aside, you could get the benefit of less typing and 
compression by doing something 
like this:

  (function(Class){
    Class.class_func = function(){
    };
  })(really_long_namespace.another_long_namespace.ClassObject);

But that wouldn't solve your issue with JsDoc.

I'm intrigued because I hadn't intended @exports to be used the way you 
describe. If you have the time I'd 
love to see a commented example that I can try out myself.

Original comment by micmath on 25 May 2010 at 8:42

GoogleCodeExporter commented 9 years ago 
> Your example is interesting, it's not something I've seen before.
I know, which makes me nervous to a degree.  There are too many other JS 
developers 
for me to be the only one who codes this way.  There has to be some huge 
downside I'm 
not seeing, but to me, this style means flexibility and efficiency.

> Can I ask why you do it that way?
Flexibility.  By specifying the namespace exactly once, my code remains loosely-
coupled, with (as far as I know) no downside.  I first started this practice 
when I 
was planning a very big project, and my code hierarchy was changing often.  It 
was 
terribly annoying to keep mass changing namespaces, testing, finding spots I 
missed, 
changing those, and so on...

As you pointed out, the clutter of the full namespace is another factor.  It 
feels 
like "syntactic overhead" if there is such a thing, and should be avoided if 
possible.

In regard to the anonymous functions using apply(), I think the only reason why 
I 
went the way I did was because I couldn't decide on a consistent keyword to use 
for 
"Class" and I know that "this" is about as universal as keywords get.  Thank 
you for 
pointing out that advantage.  I've has mixed experiences with YUI, but do like 
the 
YUI compressor and would want my code to work with it.

> If you have the time I'd love to see a commented example that I can try out 
myself.
I very much want external feedback on this style, and I'd love to see JSDOC3 
support 
this style if possible, so I have every reason to send you some code, I just 
need to 
sanitize it for publishing.  If you don't mind, I'd like to take this "offline" 
(to 
e-mail).  I found your address in the project source.  If you have any 
objections, 
please let me know.

I also came across @scope on a whim today which got me out of a uncaught JS 
exception 
that JSDOC was reporting.  I plan on reporting it soon-ish once I get some code 
together that's OK to publish.

Original comment by Elliott....@gmail.com on 28 May 2010 at 7:28

GoogleCodeExporter commented 9 years ago 
My email is public, please send me anything you like: micmath@gmail.com

Original comment by micmath on 28 May 2010 at 9:56

GoogleCodeExporter commented 9 years ago 
I have used the @exports tag in order to retain $ as the jQuery namespace:

/**
 * @exports $ as jQuery
 */
(function($) {
...
})(jQuery);

AFAIK, this is a very common practice for jQuery plugin development.  I am 
wondering, though, why you chose to call this tag "exports" instead of "alias"?

Original comment by kyle.florence@gmail.com on 11 Jun 2010 at 9:12

GoogleCodeExporter commented 9 years ago 
@alias was already in use, and had a different meaning, by an existing project 
known as scriptdoc. That project has become less popular than the commonjs 
project, which has yet another meaning for "exports". I think in JSDoc 3 the 
@exports tag will in fact be used for commonjs modules. I haven't decided yet 
if I will replace it with an @alias tag, but I may.

Original comment by micmath on 11 Jun 2010 at 11:01

GoogleCodeExporter commented 9 years ago 
Makes sense, thanks for the clarification.  If this tag is to be removed in 
JSDoc 3 (and there is no @alias replacement), how would my situation above be 
best documented?

Original comment by kyle.florence@gmail.com on 29 Jun 2010 at 8:39

GoogleCodeExporter commented 9 years ago 
There isn't a built in way to translate dollars to jQueries, but you could just 
ignore the dollared code (use the -n option for example) and provide the name 
you want documented via the @name tag.

{{{
/**
 * The jQuery library.
 * @namespace
 * @name jQuery
 */
(function($) {

    /**
     * @function
     * @name jQuery.lalala
     */
    $.lalala = function(){}

})(jQuery);
}}}

If you find that too verbose to tolerate there are some mechanisms available to 
automatically translate $->jQuery for you, see:

    http://code.google.com/p/jsdoc-toolkit/wiki/Plugins

So, in your case, you could make a file in the app/plugins folder, name it 
"whatever.js" and add the following code:

{{{
JSDOC.PluginManager.registerPlugin(
    "jQuery.renameDollar",
    {
        onDocCommentSrc: function(comment) {
            comment.src = comment.src.replace(/\$/g, 'jQuery');
        }
    }
);
}}}

(you may want to refine that regex if it's a little too brute-force for you)

Original comment by micmath on 1 Jul 2010 at 6:31