Bug 142658 – Web Inspector: Show Documentation for Prototype Functions in Object Tree API view

• Status: NEW
• Component: Web Inspector

[Joseph Pecoraro]

* SUMMARY
Show Documentation for Prototype Functions in Object Tree API view.

It is useful to see the "API" of objects in the ObjectTree view. We already show the parameter list for methods. However it would be nicer to go one step further and show documentation for the Functions/Properties/whatever of the object. Perhaps when hovering the function / Object in the ObjectTree API view.

This really has two parts:

  1. UI for Documentation
  2. Hook for getting Documentation to show


* IDEA

Provided by Browser:

  console.documentation = Symbol("documentation")

User Authored Object with documentation:

  // Class

  class Point {
    constructor(x, y) {
      this._x = x;
      this._y = y;
    },

    moveBy(x, y) {
      this._x += x;
      this._y += y;
    },

    moveBy2(x=0, y=0) {
      this.moveBy(x, y);
    },
  };

  // Documentation

  Point[console.documentation] = {
    description: "Mutable two dimensional point."
  };

  Point.prototype.moveBy[console.documentation] = {
    description: "Translate point by `x` and `y`.",
    references: [Point],
    parameters: {
      x: {type: "number", description: "x translation"},
      y: {type: "number", description: "y translation"},
    },
  };

  Point.prototype.moveBy2[console.documentation] = {
    description: "Translate point by optional `x` and `y`. Deprecated. Use `moveBy`.",
    references: [Point, Point.prototype.moveBy],
    parameters: {
      x: {type: "number", optional: true, description: "x translation", defaultValue: 0},
      y: {type: "number", optional: true, description: "y translation", defaultValue: 0},
    },
  }


* NOTES
- The structure of the documentation objects will take though. It would help to study existing "JSDoc, JavaScript, *Doc" documentation schemes to see what information is useful.
- Should we instead try to parse this information from source? That is not as accurate as just asking the object. This could be something generated from source as loaded separately, for example via a "//# documentationURL=library.js.doc" (akin to SourceMap's sourceMappingURL). After all this is mostly useful for public object APIs.
- Built-in and Native can be given documentation in the same way that we add in parameter lists.

[Radar WebKit Bug Importer]

<rdar://problem/20149853>