New Feature : Use Requirejs functionality to read JS docs from other files

[prateekjadhwani]

So, I have a bunch of files wrapped around the define block of requirejs along with its dependencies.
Is it possible to read JS docs from those files?

If you need a code example, please let me know.

Thanks

[Wikunia]

A code example would be nice ;)

[prateekjadhwani]

Let say you have a folder "assets/js"
And in this js folder you have a bunch of files. The first file "main.js" is as follows :

define('js/main', 
    ['jquery', 'underscore', 'backbone','js/utils'], 
    function($, _, Backbone, Utils) {
//                              ^---- I use this object for js/utils file and there can be n number of objects
        var mainApp = Backbone.View.extend(
         {
            /**
            *   Initializes the view for the mainApp
            */
            initialize: function(data) {
                this.utils = new Utils({
                    referrer : this
                });
                this.render();
            },
            /**
            *   Begins the render process for the mainApp
            */
            render :  function(){
                Utils.doSomeStuff();
            },
            /**
            *   Do stuff from parent for the mainApp
            */
            beginRandomProcess :  function(){
                // begin random process
            }
        });

        return mainApp;
});

And then you have another file "utils.js" in "assets/js" folder

define('js/utils', 
    ['jquery', 'underscore', 'backbone'], 
    function($, _, Backbone) {

        var Utils = Backbone.View.extend(
         {
            /**
            *   Initializes the view for the utilites
            */
            initialize: function() {
                this.referrer = this.options.referrer; // the referrer passed in the parent function comes up as this.options.referrer
                this.render();
            },
            /**
            *   Begins the render process for the utilities
            */
            render :  function(){
                this.doSomeStuff();
                this.referrer.beginRandomProcess();
            },
            /**
            *   Begins the do something process for the utilities
            */
            doSomeStuff :  function(){
               // do some stuff
            }
        });

        return Utils;
});

There can be nested folders indicating that there are submodules.
That moves us to the next topic, Submodules trying to call functions from its parent, also called as Referrer. So when we try to access the referrer.beginRandomProcess, it should try to access the docs for the parent view from the referrer's object.

Let me know what do you think about it.

[Wikunia]

A few questions because I don't know backbone.js:

1. define use two parameters a string (kind of class name) and an array?
2. the array entries are sth like import these files?
3. the name of the variable and the filename are always the same? (in this case Utitls = utils.js)

[sbruchmann]

@Wikunia define is not related to Backbone.js, it’s a standard method for defining a module when using AMD. The most popular JavaScript library providing AMD capabilities is require.js. If you want to read more about the syntax/api, than you can do this at http://requirejs.org/docs/api.html#define

Hope that helps.

[prateekjadhwani]

Regarding your 1st and 2nd questions, Define uses 3 parameters

1. is the name of that module that it will be accessed with from anywhere.
   2.The list of modules that it needs to import.
   3 The Object it needs to call that Module with

So for example, you have a module like this

define('main',  {
   var viewX = Backbone.View.Extend({
   });
   return viewX;
});

and

define('utils', 
    ['main'], 
    function(myMainObject) {
   // inner stuff
});

So here 'js/utils' is the name module. I can name it anything. If you see the 2nd code example, 'main' is the name of the module that needs to be imported. Where as it is created and defined in the first section of the code. And myMainObject is the name of the object that you want to call the returned object in the first section of the code. SO technically, the viewX returned in "main" module will be called as myMainObject in the "utils" module. And as @sbruchmann said, "define" is not related to the Backbone view, but the objects returned are Backbone Views.

Regarding 3rd question. I try to use the convention that makes it easy to identify a module. But it may or may not be same.

[Wikunia]

I need some time to understand it and don't know how to implement this the best way.

[prateekjadhwani]

I understand your pain. Dont worry too much, its just a feature request. Meanwhile, even I am going through the extension, trying to figure out the same thing.

Fingers crossed.

[Wikunia]

Okay I will make a requirejs branch tonight or tomorrow and you can test and debug a bit, is this a plan? :D

[prateekjadhwani]

Works for me. :)

[Wikunia]

You can install this branch! It should work for modules which have defined names like in your example and it isn't really intelligent, so it scans all files :/ But I will work on that :)
And another question:

define('js/main', 
    ['jquery', 'underscore', 'backbone','js/utils'], 

are utils.js and main.js in the same directory (js) ? And only utils would mean that it's in the parent folder?

[prateekjadhwani]

Utils.js and Main.js may or may not in the same folder. "js/main" and "js/utils" is the convention that i use to indicate that main and utils modules are in js folder. Its name can be anything.

[Wikunia]

So I need to scan all files? This http://requirejs.org/docs/api.html#modulename says
These are normally generated by the optimization tool. You can explicitly name modules yourself, but it makes the modules less portable -- if you move the file to another directory you will need to change the name.
So the name of the module must be the filename (including directory changes). Is this wrong? :/

[prateekjadhwani]

No, its not wrong. I guess I lacked domain knowledge then. From the link that you see, i Do see that its the relative path.

[Wikunia]

Can you try this version pls! I need a break now :D

[prateekjadhwani]

Wow It works!!!
It works when we try to access an object of a child class. +1 for that :)
Regarding the referrer stuff. Lets forget about it for the time being.

So I think we can close this issue.

Thanks Man!!!

[Wikunia]

That sounds like music in my ears :D
I will remove the logs and register the new version! Have fun within your company ;)

[prateekjadhwani]

👍