1. #211
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    Doh! Didn't even think of that.

    I'm working with legacy-non Ext code and having a lot of trouble getting it to properly doc global functions. It seems to want to put the methods into prior classes that they don't apply to.

    I've tried separating some of these globals out to a separate file just to pull into jsDuck and that seems to work better, however it's not a viable option given the monstrous size of this codebase to start re-arranging code just for doc purposes.

    Any ideas what I'm might be missing?

  2. #212
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default


    There are two options here.

    You can add a doc-comment with /** @class global */ before those functions - all the functions documented after that will end up in a special global class.

    You can add @member global inside the doc-comment of the function itself.

  3. #213
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    Great. I'll give that a shot when I return from the holiday.

  4. #214
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    Making some progress trying to reformat my comments, but still running into some issues:
    1) Can extensions to base objects (e.g. String, Array) be shown under something other than 'global' - with or without using "--builtin-classes": true

    2) getting inline examples to format - tried multiple varieties of spacing, none successfully.
    Code:
    if (!String.prototype.replaceAll) {
    /**
     * @method
     * Replace all instances of one string within another string.
     * @param {String} find the string to find.
     * @param {String} replace the string to replace with.
     * @return the modified string.
     * Example:
     *
     *     ' foobar'.replaceAll("o", "-");		// returns "f--bar"
     *     "fo o b a r".replaceAll(" ", "");	// returns "foobar"
    */
    	String.prototype.replaceAll = function(find, replace) {
    	    return this.split(find).join(replace);
    	};
    }
    
    if (!String.prototype.trim) {
    /**
     * @extends String
     * Return string with leading and trailing spaces removed.
     * @return the trimmed string.
     * @example
     *     ' foobar'.trim();	// returns 'foobar'
     *     'foobar '.trim();	// returns 'foobar'
     *     ' foobar '.trim();	// returns 'foobar'
     *     'foo bar'.trim();	// returns 'foo bar'
    */
    	String.prototype.trim = function() {
    		return this.replace(/^\s+|\s+$/g, '');
    	};
    }
    
    if (!String.prototype.ltrim) {
    /**
     * @method
     * Return string with leading spaces removed.
     * @return the trimmed string.
     * @example
     *	' foobar'.ltrim();	// returns 'foobar'
     *	' foobar '.ltrim();	// returns 'foobar '
     *	'foo bar'.ltrim();	// returns 'foo bar'
    */
    	String.prototype.ltrim = function() {
    		return this.replace(/^\s+/, '');
    	};
    }
    3) Getting functions in a singleton to generate
    Code:
    /**
    * @class
    * Implements cookie-less JavaScript session variables.
    * @singleton
    */
    var Session = (function() {
     var win = window.top || window,
    	//adding extra check here - sometimes IE reporting name='undefined'
    	store = (!!win.name && win.name !== 'undefined' ? JSON.parse(win.name) : {}); 
    /**
    * Save store on page unload
    * @ignore
    */
    function Save() {
    	win.name = JSON.stringify(store);
    }
    
    // public methods
    return {
    	/**
    	 * @method
    	 * Set a Session variable
    	 * @param {String} name key for the entry
    	 * @param {Mixed} value the value to be stored
    	 * @return void
    	*/
    	set: function(name, value) {
    		store[name] = value;
    	},
     ....
          };
    })();
    Thanks

  5. #215
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    I've resolved the commenting issue by switching the format to the following:
    Code:
     * @return {String} the modified string.
     *
    	//Example
    	' foobar'.replaceAll('o', '-');		// returns "f--bar"
    	'fo o b a r'.replaceAll(' ', '');	// returns "foobar"
    */

  6. #216
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default


    1) Can extensions to base objects (e.g. String, Array) be shown under something other than 'global' - with or without using "--builtin-classes": true
    Use @member String and the method will get added to String class.

    2) getting inline examples to format - tried multiple varieties of spacing, none successfully.
    The first problem you stumbled upon was that you didn't specify the type of return values, and so the return value documentation didn't show up in documentation at all. That's a bug in JSDuck, which I'll fix but in the mean time you should specify these types, which is a good practice to do anyway.

    The @example tag is meant for live inline examples that can be executed inside documentation, like can be seen in ExtJS or Touch docs. Your examples don't produce any output, so it doesn't make sense to use @example with them. But if you really want to turn them into live examples, you need to also indent the @example tag, otherwise it's not recognized by JSDuck.

    The main thing though, is that you need to add an empty line between the indented example and comment text preceding it.

    Finally, you shouldn't put your example code after @return tag, unless you intend to provide examples to explain the return value. Although your examples demonstrate the return value, I'd say they really are examples of the whole method, so I'd write them like this:

    Code:
    /**
     * Replaces all instances of one string within another string.
     *
     *     'foobar'.replaceAll('o', '-');   // returns "f--bar"
     *     'fo o b a r'.replaceAll(' ', '');  // returns "foobar"
     *
     * @param {String} find the string to find.
     * @param {String} replace the string to replace with.
     * @return {String} the modified string.
     */
    3) Getting functions in a singleton to generate
    You've stumbled upon a case, which can look quite mysterious when you're not overly familiar with JSDuck.

    You're using the @ignore tag to ignore the Save function. But JSDuck doesn't know it's just a function - it sees that it's beginning with an uppercase letter and therefore thinks that by convention Save must be a class. So all the methods now following this will end up in this Save class and the class itself will get ignored.

    One solution is to simply inform JSDuck that Save is a simple method:

    Code:
    /**
    * Save store on page unload
    * @ignore
    * @method
    */
    function Save() {
    	win.name = JSON.stringify(store);
    }
    Alternatively you can just use a line-comment and JSDuck won't bother looking at it:

    Code:
    // Save store on page unload
    function Save() {
    	win.name = JSON.stringify(store);
    }

  7. #217
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    Great I think I've got everything covered now.

    Thanks for your help.

  8. #218
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    Ran into a new one trying to document some jQuery extensions. I'm not including the jQuery lib in my jsDuck config, but I am doing
    "--external":"jQuery"
    Code:
    /**
     * @class
     * @extends jQuery
     * Querystring access.  This is the only way querystring processing should be done.<br />
     * http://archive.plugins.jquery.com/project/query-object (currently down)
    */
    	jQuery.query = new function () {
    ...
    /**
     * @class jQuery.q
     * @extends jQuery
     * @chainable
     * jQuery selector caching<br />
     * This function is used to cache a jQuery selector to avoid repeatedly..
     * @param {String} selector any jQuery selector string
     * @param {Boolean} [clear=false] force the cache for this selector to be cleared and re-read from DOM
     * @return {jQuery}
    */
        jQuery.q = function (selector, clear) {..
    The above generates correctly and I get a jQuery class heirarchy with 'q' and 'query' documented correctly.
    Further down in the same file, I have
    Code:
    /**
     * @method foo
     * @member jQuery
     * dummy function
     * @param {Number} x sdfsfk
     * @return void
    */
    jQuery.foo = function(x) {
    	x++;
    };
    This generates a warning for 'Global method:foo' and puts it under global namespace. I've tried multiple varieties of method/member/extends tags for this, with no success.

    This also brought to light another issue:
    I have many other functions marked with @member Global, which gen correctly until the above code is added. It then creates a 'global' entry and then 'Global' and 'global' seem to collide and both entries get created in the left panel, but 'Global' doesn't get any content b/c MS doesn't see case sensitivity in filenames.

    I could obviously handle this by changing my tags to @member Global, but if I could get 'foo' to behave it wouldn't be an issue.

    Should I try to add dummy doc for a @class jQuery ahead of this? Will jsDuck see it with no subsequent code after the comment block?

  9. #219
    Sencha User
    Join Date
    Mar 2007
    Posts
    7,854
    Vote Rating
    4
    tryanDLS is on a distinguished road

      0  

    Default


    Took a shot in the dark and added
    /**
    * @class jQuery
    * jQuery library is documented here <http://jqapi.com>
    */

    which seems to have solved the problem.

  10. #220
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default


    This generates a warning for 'Global method:foo' and puts it under global namespace.
    Which version of JSDuck are you using? With the latest 4.5.1 using your code the foo method ends up nicely in jQuery class.

    Your solution to just add a doc-comment defining the jQuery class is a good one though.

    However you seem to be doing something quite weird in your code:

    Code:
    /**
     * @class jQuery.q
     * @extends jQuery
     * @chainable
     * jQuery selector caching<br />
     * This function is used to cache a jQuery selector to avoid repeatedly..
     * @param {String} selector any jQuery selector string
     * @param {Boolean} [clear=false] force the cache for this selector to be cleared and re-read from DOM
     * @return {jQuery}
    */
        jQuery.q = function (selector, clear) {..
    It looks like you try to document jQuery.q as a class and as a method at the same time. JSDuck sees @class and therefore documents it as a class, ignoring all the @param and @return tags.

    I'd say you aren't subsclassing the jQuery class in here - rather you just add an extra "q" method to it. Therefore you should simply document it as a method and add @member jQuery.

    I have many other functions marked with @member Global, which gen correctly until the above code is added. It then creates a 'global' entry and then 'Global' and 'global' seem to collide and both entries get created in the left panel, but 'Global' doesn't get any content b/c MS doesn't see case sensitivity in filenames.
    Do you really have a class called Global or have you just marked global functions with @member Global?

    - in the first case, you're really in an unfortunate situation, and we'd need to dig deeper.
    - in the latter case the JSDuck convention is to put global functions to a class called "global", and I suggest you follow that.