/branches/version1.x/app/DocTag.js

http://jsdoc-toolkit.googlecode.com/ · JavaScript · 137 lines · 82 code · 14 blank · 41 comment · 43 complexity · f19eda9ddfd563bc8180c2a68ccfcc61 MD5 · raw file

  1. /**
  2. * @fileOverview
  3. * @name DocTag
  4. * @author Michael Mathews micmath@gmail.com
  5. * @url $HeadURL: http://jsdoc-toolkit.googlecode.com/svn/branches/version1.x/app/DocTag.js $
  6. * @revision $Id: DocTag.js 405 2007-12-28 23:39:50Z micmath $
  7. * @license <a href="http://en.wikipedia.org/wiki/MIT_License">X11/MIT License</a>
  8. * (See the accompanying README file for full details.)
  9. */
  10. /**
  11. * @class Represents a tag within a doclet.
  12. * @author Michael Mathews <a href="mailto:micmath@gmail.com">micmath@gmail.com</a>
  13. * @constructor
  14. * @param {string} src line(s) of text following the @ character
  15. */
  16. function DocTag(src) {
  17. /**
  18. * Like @title
  19. * @type string
  20. */
  21. this.title = "";
  22. /**
  23. * Like @title {type}
  24. * @type string
  25. */
  26. this.type = "";
  27. /**
  28. * Like @title {type}? name, though this is only recognized in tags with a title of "param" or "property."
  29. * @type string
  30. */
  31. this.name = "";
  32. /**
  33. * Like @title {type}? name? description goes here...
  34. * @type string
  35. */
  36. this.desc = "";
  37. /**
  38. * Like @title {type} [name=defaultValue] description goes here...
  39. * @type string
  40. */
  41. this.defaultValue = "";
  42. if (typeof(src) != "undefined") {
  43. var parts = src.match(/^(\S+)(?:\s+\{\s*([\S\s]+?)\s*\})?\s*([\S\s]*\S)?/);
  44. this.title = (parts[1].toLowerCase() || "");
  45. this.type = (parts[2] || "");
  46. if (this.type) this.type = this.type.replace(/\s*(,|\|\|?)\s*/g, ", ");
  47. this.desc = (parts[3] || "");
  48. // should be @type foo but we'll accept @type {foo} too
  49. if (this.title == "type") {
  50. if (this.type) this.desc = this.type;
  51. // should be @type foo, bar, baz but we'll accept @type foo|bar||baz too
  52. if (this.desc) {
  53. this.desc = this.desc.replace(/\s*(,|\|\|?)\s*/g, ", ");
  54. }
  55. }
  56. var syn;
  57. if ((syn = DocTag.synonyms["="+this.title])) this.title = syn;
  58. if (this.desc) {
  59. if (this.title == "param") { // long tags like {type} [name] desc
  60. var m = this.desc.match(/^\s*\[([a-zA-Z0-9.$_]+)(?:\s*=([^\]]+))?\](?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
  61. if (m) { // optional parameter
  62. this.isOptional = true; // bracketed name means optional
  63. this.name = (m[1] || "");
  64. this.defaultValue = (m[2] || "");
  65. this.type = (m[3] || this.type);
  66. this.desc = (m[4] || "");
  67. }
  68. else { // required parameter
  69. var m = this.desc.match(/^\s*([a-zA-Z0-9.$_]+)(?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
  70. if (m) {
  71. this.isOptional = false;
  72. this.name = (m[1] || "");
  73. this.type = (m[2] || this.type);
  74. this.desc = (m[3] || "");
  75. }
  76. }
  77. }
  78. else if (this.title == "property") {
  79. var m = this.desc.match(/^\s*([a-zA-Z0-9.$_]+)(?:\s+([\S\s]*\S))?/);
  80. if (m) {
  81. this.name = (m[1] || "");
  82. this.desc = (m[2] || "");
  83. }
  84. }
  85. else if (this.title == "config") {
  86. var m = this.desc.match(/^\s*\[([a-zA-Z0-9.$_]+)(?:\s*=([^\]]+))?\](?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
  87. if (m) { // optional parameter
  88. this.isOptional = true; // bracketed name means optional
  89. this.name = (m[1] || "");
  90. this.defaultValue = (m[2] || "");
  91. this.type = (m[3] || this.type);
  92. this.desc = (m[4] || "");
  93. }
  94. else { // required parameter
  95. m = this.desc.match(/^\s*([a-zA-Z0-9.$_]+)(?:\s+\{\s*([\S\s]+?)\s*\})?(?:\s+([\S\s]*\S))?/);
  96. if (m) {
  97. this.isOptional = false;
  98. this.name = (m[1] || "");
  99. this.type = (m[2] || this.type);
  100. this.desc = (m[3] || "");
  101. }
  102. }
  103. }
  104. }
  105. }
  106. }
  107. /**
  108. * Used to make various JsDoc tags compatible with JsDoc Toolkit.
  109. * @memberOf DocTag
  110. */
  111. DocTag.synonyms = {
  112. "=member": "memberof",
  113. "=description": "desc",
  114. "=exception": "throws",
  115. "=argument": "param",
  116. "=returns": "return",
  117. "=classdescription": "class",
  118. "=fileoverview": "overview",
  119. "=extends": "augments"
  120. }
  121. DocTag.prototype.toString = function() {
  122. return this.desc;
  123. }