/wiki/TagLends.wiki

http://jsdoc-toolkit.googlecode.com/ · Unknown · 90 lines · 75 code · 15 blank · 0 comment · 0 complexity · 3e72ca1c5416006b14eb761ec5eaaf90 MD5 · raw file

  1. #summary @lends
  2. == The @lends Tag ==
  3. The `@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.
  4. === Syntax ===
  5. {{{
  6. @lends symbolAlias
  7. }}}
  8. * symbolAlias - Required: the full namepath to the object you are lending methods and properties to.
  9. * Note: The doc comment containing the `@lends` tag must immediately precede an object literal in your code.
  10. === Example ===
  11. In 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.
  12. {{{
  13. // we want to document this as being a class
  14. var Person = makeClass(
  15. // we want to document these as being methods
  16. {
  17. initialize: function(name) {
  18. this.name = name;
  19. },
  20. say: function(message) {
  21. return this.name + " says: " + message;
  22. }
  23. }
  24. );
  25. }}}
  26. Without 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."
  27. {{{
  28. /** @class */
  29. var Person = makeClass(
  30. /** @lends Person */
  31. {
  32. initialize: function(name) {
  33. this.name = name;
  34. },
  35. say: function(message) {
  36. return this.name + " says: " + message;
  37. }
  38. }
  39. );
  40. }}}
  41. Now 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:
  42. {{{
  43. /** @class */
  44. var Person = makeClass(
  45. /** @lends Person.prototype */
  46. {
  47. initialize: function(name) {
  48. this.name = name;
  49. },
  50. say: function(message) {
  51. return this.name + " says: " + message;
  52. }
  53. }
  54. );
  55. }}}
  56. If 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.
  57. {{{
  58. var Person = makeClass(
  59. /**
  60. @lends Person.prototype
  61. */
  62. {
  63. /** @constructs */
  64. initialize: function(name) {
  65. this.name = name;
  66. },
  67. say: function(message) {
  68. return this.name + " says: " + message;
  69. }
  70. }
  71. );
  72. }}}
  73. == See Also ==
  74. * The [TagBorrows @borrows] tag.
  75. * The [TagConstructs @constructs] tag.