Documenting built-in classes

[GoogleCodeExporter]

Refers to: 2.0 beta

When extending built-in classes, e.g. String, is there a way to provide a
leading documentation that summarizes the extensions for that particular class?

Consider the following code, an extract of prototype.js, with added doclets.

/**
 * The String prototype is extended by numerous utility
 * methods, e.g. {@link #strip()}.
 *
 * This comment should appear as the introductory text for
 * the String class inside the documentation. However,
 * there seems to be no way to get it included properly.
 * Neither @class nor @namespace seem to help.
 */
Object.extend(String.prototype, 
/** @lends String.prototype */ 
{
  /**
   * Returns a trimmed version of this string.
   * @return Trimmed string
   */
  strip: function() {
    return this.replace(/^\s+/, '').replace(/\s+$/, '');
  }
});

Original issue reported on code.google.com by til...@gmail.com on 3 Apr 2008 at 5:43

[GoogleCodeExporter]

I'm using Revision 557, soon to be released as 2.0 beta2, and the following 
works for me:

/**
 * @name String
 * @class
 * The String prototype is extended by numerous utility
 * methods, e.g. {@link #strip()}.
 *
 * This comment should appear as the introductory text for
 * the String class inside the documentation. However,
 * there seems to be no way to get it included properly.
 * Neither @class nor @namespace seem to help.
 */
Object.extend(String.prototype, 
/** @lends String.prototype */ 
{
  /**
   * Returns a trimmed version of this string.
   * @return Trimmed string
   */
  strip: function() {
    return this.replace(/^\s+/, '').replace(/\s+$/, '');
  }
});

Please confirm if this solves your issue?

Original comment by micmath on 5 Apr 2008 at 5:36

• Changed state: Invalid
• Added labels: Type-Enhancement
• Removed labels: Type-Defect