610729 - Update Markdown files to new class syntax

Status: RESOLVED FIXED

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

Description

[Will Bamberg [:wbamberg]]

Attachment: Patch containing all the updates to the markdown files

Update Markdown files API syntax so that objects contain any properties and methods which are their members.

This is the remaining part of bug605627, which updates the syntax definition (apiparser.py) and the rendering code that interprets the syntax.

Comment 1

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

Comment on attachment 489223 [details] [diff] [review]
Patch containing all the updates to the markdown files

>diff --git a/packages/addon-kit/docs/clipboard.md b/packages/addon-kit/docs/clipboard.md

>+      require("tabs").open("data:text/html," + clipboard.get("html"));

Aside: this should URI-encode the HTML string, i.e.:

      require("tabs").open("data:text/html," +
                           encodeURIComponent(clipboard.get("html")));


>diff --git a/packages/addon-kit/docs/context-menu.md b/packages/addon-kit/docs/context-menu.md

> <api name="Item">
>+@class
>+A single item to be added to the context menu.
>+<api name="Item">
> @constructor
>   Creates a labeled menu item that can perform an action when clicked.
> @param options {object}
>@@ -259,8 +366,12 @@ Reference
>     data that was passed to `postMessage`.  Ignored if the item is contained in
>     a submenu.
> </api>
>+</api>

Aside: these nested <api> tags with identical `name`s are funky; it takes a bit of time to wrap one's brain around them (I'm not sure mine is quite wrapped yet, actually).


>diff --git a/packages/addon-kit/docs/page-mod.md b/packages/addon-kit/docs/page-mod.md

>+<api name="PageMod">
>+	@class

Nit: there's an extraneous tab character here that should be removed (it appears to be the only one in the patch).


>diff --git a/packages/addon-kit/docs/request.md b/packages/addon-kit/docs/request.md

>     @prop onComplete {callback}
>     This function will be called when the request has received a response. In
>-    terms of XHR, when `readyState == 4`. The `responce` & `request` objects
>+    terms of XHR, when `readyState == 4`. The `response` & `request` objects
>     are passed to the callback as an arguments.

Nice catch!  We should probably also do s/as an arguments/as arguments/.


>diff --git a/packages/jetpack-core/docs/api-utils.md b/packages/jetpack-core/docs/api-utils.md

>+    var opts = { foo: 1337 };
>+    var requirements = {
>+      foo: {
>+        map: function (val) val.toString(),
>+        is: ["string"],
>+        ok: function (val) val.length > 0,
>+        msg: "foo must be a non-empty string."
>+      }
>+    };
>+    var validatedOpts = apiUtils.validateOptions(opts, requirements);
>+    // validatedOpts == { foo: "1337" }
>+If the key `foo` is optional and doesn't need to be mapped:

Nit: the original had a blank line between the example and the line of prose, which makes the text easier to read, so the new version should do the same.


>diff --git a/packages/jetpack-core/docs/byte-streams.md b/packages/jetpack-core/docs/byte-streams.md

>+  The backing stream, an <a href="http://mxr.mozilla.org/mozilla-central/
>+source/xpcom/io/nsIInputStream.idl"><code>nsIInputStream</code></a>.

Aside: we should convert <code>...</code> to `...` in these docs.


>diff --git a/packages/jetpack-core/docs/content/symbiont.md b/packages/jetpack-core/docs/content/symbiont.md

>-[panel]:https://jetpack.mozillalabs.com/sdk/latest/docs/#module/jetpack-core/panel
>+[panel]:#module/jetpack-core/panel

Aside: nice fixes!  They mean that this bug also fixes bug 610030.


>diff --git a/packages/jetpack-core/docs/list.md b/packages/jetpack-core/docs/list.md

>+List is a base trait and is meant to be a part of
>+composition, since all of its API is private except for the `length` property.

One more grammar nit here: a part of composition -> part of a composition.

Comment 2

[Will Bamberg [:wbamberg]]

> >-[panel]:https://jetpack.mozillalabs.com/sdk/latest/docs/#module/jetpack-core/panel
> >+[panel]:#module/jetpack-core/panel
> 
> Aside: nice fixes!  They mean that this bug also fixes bug 610030.

Unfortunately, because the files are organized differently in the SDK and the AOB, none of these internal links work in the AOB :-(. Maybe I should raise another defect to track that? Although I'm not too sure what best resolution is.

Comment 3

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

(In reply to comment #2)
> > >-[panel]:https://jetpack.mozillalabs.com/sdk/latest/docs/#module/jetpack-core/panel
> > >+[panel]:#module/jetpack-core/panel
> > 
> > Aside: nice fixes!  They mean that this bug also fixes bug 610030.
> 
> Unfortunately, because the files are organized differently in the SDK and the
> AOB, none of these internal links work in the AOB :-(. Maybe I should raise
> another defect to track that?

Sounds like a good idea.  Alternately, morph bug 610030 to be about making the links all relative in a way that works for both the SDK and the AOB docs.

Comment 4

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

The Add-on SDK is no longer a Mozilla Labs experiment and has become a big enough project to warrant its own Bugzilla product, so the "Add-on SDK" product has been created for it, and I am moving its bugs to that product.

To filter bugmail related to this change, filter on the word "looptid".

Comment 5

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

Landed, with nits fixed, as https://github.com/mozilla/addon-sdk/commit/5d3680b5663ac58b70149de93b420a76ee66a8d5.