/wiki/TagLends.wiki

 1#summary @lends
 2
 3== The @lends Tag ==
 4
 5The `@lends` tag allows you to document all the members of an anonymous object literal as if they were members of an object with the given name. You might want to do this if you were passing an anonymous object literal into a function that creates a named class from its members.
 6
 7=== Syntax ===
 8{{{
 9@lends symbolAlias
10}}}
11
12  * symbolAlias - Required: the full namepath to the object you are lending methods and properties to.
13  * Note: The doc comment containing the `@lends` tag must immediately precede an object literal in your code.
14  
15=== Example ===
16
17In this example we want to use a helper function to make a class named "Person," along with instance methods named "initialize" and "say." This is similar to how some popular frameworks handle class creation.
18
19{{{
20// we want to document this as being a class
21var Person = makeClass(
22    // we want to document these as being methods
23    {
24        initialize: function(name) {
25            this.name = name;
26        },
27        say: function(message) {
28            return this.name + " says: " + message;
29        }
30    }
31);
32}}}
33
34Without any doc comments !JsDoc Toolkit won't automatically recognize either a class named "Person" nor it's two methods. To document the methods we must use a "@lends" tag in a doc comment immediately before the object literal to tell !JsDoc Toolkit that all the member names of that object literal are being "lent" to a variable named "Person."
35
36{{{
37/** @class */
38var Person = makeClass(
39    /** @lends Person */
40    {
41        initialize: function(name) {
42            this.name = name;
43        },
44        say: function(message) {
45            return this.name + " says: " + message;
46        }
47    }
48);
49}}}
50
51Now the functions named "initialize" and "say" will be documented, but they appear as static methods of an class named "Person." That is possibly what you meant, but in this case we want "initialize" and "say" to belong to the _instances_ of the "Person" class. So we change things slightly by lending the methods to the class's prototype:
52
53{{{
54/** @class */
55var Person = makeClass(
56    /** @lends Person.prototype */
57    {
58        initialize: function(name) {
59            this.name = name;
60        },
61        say: function(message) {
62            return this.name + " says: " + message;
63        }
64    }
65);
66}}}
67
68If you are using one of the lent functions to construct the class, you can mark it as such using the `@constructs` tag, but remember to remove the @class tag in that case, or else two @classes will be documented.
69
70{{{
71var Person = makeClass(
72    /**
73      @lends Person.prototype
74    */
75    {
76        /** @constructs */
77        initialize: function(name) {
78            this.name = name;
79        },
80        say: function(message) {
81            return this.name + " says: " + message;
82        }
83    }
84);
85}}}
86
87== See Also ==
88  * The [TagBorrows @borrows] tag.
89  * The [TagConstructs @constructs] tag.
90