You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: tags-lends.html
+37-11Lines changed: 37 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -44,7 +44,7 @@ <h2 id="overview">Overview</h2>
44
44
<p>The <code>@lends</code> tag allows you to document all the members of an object literal as if they were members of a symbol with the given name. You might want
45
45
to do this if you are passing an object literal into a function that creates a named class from its members.</p>
46
46
<h2id="examples">Examples</h2>
47
-
<p>In this example, we want to use a helper function to make a class named "Person," along with instance methods named "initialize" and "say."
47
+
<p>In this example, we want to use a helper function to make a class named <code>Person</code>, along with instance methods named <code>initialize</code> and <code>say</code>.
48
48
This is similar to how some popular frameworks handle class creation.</p>
49
49
<figure>
50
50
<figcaption>Example class</figcaption><preclass="prettyprint lang-js"><code>// We want to document this as being a class
<p>Without any comments, JSDoc won't recognize that this code creates a "Person" class with two methods. To document the methods, we must use a "@lends"
65
-
tag in a doc comment immediately before the object literal. The @lends tag tells JSDoc that all the member names of that object literal are being "lent"
66
-
to a variable named "Person."</p>
64
+
<p>Without any comments, JSDoc won't recognize that this code creates a <code>Person</code> class with two methods. To document the methods, we must use a <code>@lends</code> tag in a doc comment immediately before the object literal. The <code>@lends</code> tag tells JSDoc that all the member names of that object literal are being
65
+
"loaned" to a variable named <code>Person</code>. We must also add comments to each of the methods.</p>
67
66
<p>The following example gets us closer to what we want:</p>
68
67
<figure>
69
68
<figcaption>Documented as static methods</figcaption><preclass="prettyprint lang-js"><code>/** @class */
70
69
var Person = makeClass(
71
70
/** @lends Person */
72
71
{
72
+
/**
73
+
* Create a `Person` instance.
74
+
* @param {string} name - The person's name.
75
+
*/
73
76
initialize: function(name) {
74
77
this.name = name;
75
78
},
79
+
/**
80
+
* Say something.
81
+
* @param {string} message - The message to say.
82
+
* @returns {string} The complete message.
83
+
*/
76
84
say: function(message) {
77
85
return this.name + " says: " + message;
78
86
}
79
87
}
80
88
);
81
89
</code></pre>
82
90
</figure>
83
-
<p>Now the functions named "initialize" and "say" will be documented, but they appear as static methods of the "Person" class. That
84
-
is possibly what you meant, but in this case we want "initialize" and "say" to belong to the instances of the "Person" class.
85
-
So we change things slightly by lending the methods to the class's prototype:</p>
91
+
<p>Now the functions named <code>initialize</code> and <code>say</code> will be documented, but they appear as static methods of the <code>Person</code> class.
92
+
That is possibly what you meant, but in this case we want <code>initialize</code> and
93
+
<code>say</code> to belong to the instances of the <code>Person</code> class. So we change things slightly by lending the methods to the class's prototype:</p>
86
94
<figure>
87
95
<figcaption>Documented as instance methods</figcaption><preclass="prettyprint lang-js"><code>/** @class */
88
96
var Person = makeClass(
89
97
/** @lends Person.prototype */
90
98
{
99
+
/**
100
+
* Create a `Person` instance.
101
+
* @param {string} name - The person's name.
102
+
*/
91
103
initialize: function(name) {
92
104
this.name = name;
93
105
},
106
+
/**
107
+
* Say something.
108
+
* @param {string} message - The message to say.
109
+
* @returns {string} The complete message.
110
+
*/
94
111
say: function(message) {
95
112
return this.name + " says: " + message;
96
113
}
97
114
}
98
115
);
99
116
</code></pre>
100
117
</figure>
101
-
<p>One final step: Our class framework uses the loaned "initialize" function to construct Person instances, but a Person instance does not have its own
102
-
"initialize" method. The solution is to add the @constructs tag to the loaned function. Remember to remove the @class tag as well, or else two classes
103
-
will be documented.</p>
118
+
<p>One final step: Our class framework uses the loaned <code>initialize</code> function to construct <code>Person</code> instances, but a <code>Person</code> instance
119
+
does not have its own <code>initialize</code> method. The solution is to add the <code>@constructs</code> tag to the loaned function. Remember to remove the
120
+
<code>@class</code> tag as well, or else two classes will be documented.</p>
104
121
<figure>
105
122
<figcaption>Documented with a constructor</figcaption><preclass="prettyprint lang-js"><code>var Person = makeClass(
0 commit comments