[Webkit-unassigned] [Bug 142658] New: Web Inspector: Show Documentation for Prototype Functions in Object Tree API view

[bugzilla-daemon at webkit.org]

https://bugs.webkit.org/show_bug.cgi?id=142658

            Bug ID: 142658
           Summary: Web Inspector: Show Documentation for Prototype
                    Functions in Object Tree API view
    Classification: Unclassified
           Product: WebKit
           Version: 528+ (Nightly build)
          Hardware: All
                OS: All
            Status: NEW
          Severity: Normal
          Priority: P2
         Component: Web Inspector
          Assignee: webkit-unassigned at lists.webkit.org
          Reporter: joepeck at webkit.org
                CC: burg at cs.washington.edu, graouts at webkit.org,
                    joepeck at webkit.org, jonowells at apple.com,
                    mattbaker at apple.com, nvasilyev at apple.com,
                    timothy at apple.com, webkit-bug-importer at group.apple.com

* 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.

-- 
You are receiving this mail because:
You are the assignee for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-unassigned/attachments/20150313/5149c113/attachment-0002.html>