616736 - Improve widget doc further

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect)

Description

[Drew Willcoxon :adw]

Attachment: patch

This patch makes these changes:

* label is a required option, not an optional option, so brackets
  should not be used
* documents widget instance properties (none currently are), including
  properties and methods inherited from Loader and EventEmitter
* adds a section on widget events
* misc wording improvements

Comment 1

[Drew Willcoxon :adw]

Oh, it also corrects some other inaccuracies:

* currently contentScript and contentScriptFile are said to be arrays,
  but they can also be strings
* the formatting of `allow` is incorrect and makes it seem like its
  `script` property is actually a property of the options object
  passed to the Widget ctor

... so technically this should block beta 1.

Comment 2

[Drew Willcoxon :adw]

Attachment: patch 2

Actually contentURL in the options object is a string, not a "URL", and the contentURL property of Widget instances is a URL object, not a string.

Comment 3

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 495289 [details] [diff] [review]
patch 2

>-  @prop [onClick] {callback}
>-    An optional function to be called when the widget is clicked. It is called
>-    as `onClick(widget)`, where `widget` is the `Widget` instance.
>+  @prop [onClick] {function}
>+    An optional "click" event listener.  See Events above.

It's too bad the docs use fragments to refer to pages, since that makes it hard to refer to anchors (such as "Events" in this text, which would ideally link to the Events section of this page).

Anyway, this looks great, r=myk!

Comment 4

[Drew Willcoxon :adw]

https://github.com/mozilla/addon-sdk/commit/0f1286c69f1546d31ca7435e8ce26b7e9f4267f0

https://github.com/mozilla/addon-sdk/commit/63960956dd59e6dd2851db982cb3ad1cfa18223e

Comment 5

[Drew Willcoxon :adw]

(In reply to comment #3)
> It's too bad the docs use fragments to refer to pages, since that makes it hard
> to refer to anchors (such as "Events" in this text, which would ideally link to
> the Events section of this page).

Yeah, this has come up several times before.  We should make each page of the docs a proper page.

Comment 6

[Myk Melez [:myk] [@mykmelez]]

https://github.com/mozilla/addon-sdk/commit/69182feb6bf144f9adedfb21ef3d37648b573317
https://github.com/mozilla/addon-sdk/commit/0dad5174e34252907d053167cf206b72aae000ec