Permalink
Browse files

Improve documentation & add more examples to highlight that multiple …

…namespaces maybe used with a single object.
  • Loading branch information...
1 parent 3313ab7 commit 550e74dd39314cb4b55ae41fc4d610931b25621c @Gozala committed Nov 11, 2011
Showing with 60 additions and 8 deletions.
  1. +60 −8 packages/api-utils/docs/namespace.md
@@ -1,12 +1,64 @@
Provides an API for creating namespaces for any given objects, which
-effectively may be used for storing private data associated with a given
-object.
+effectively may be used for creating fields that are not part of objects
+public API.
- let { Namespace } = require("api-utils/namespace");
- let _ = Namespace()
+ let { Namespace } = require('api-utils/namespace');
+ let ns = Namespace();
@warner

warner Nov 18, 2011

calling it "my"-something might be another way to remind people that you can keep the ns object private if you want to, and that different code can create different instances. maybe "myNS"?

- _(publicAPI).secret = secret
+ ns(publicAPI).secret = secret;
-Also, note that one namespace can be used for multiple objects and multiple
-namespaces can be used with one object. In addition access to the namespace
-can be shared by just handing them a namespace access function `_`.
+One namespace may be used for may be used with multiple objects:
@warner

warner Nov 18, 2011

typo, should be "One namespace may be used with multiple objects"

+
+ let { Namespace } = require('api-utils/namespace');
+ let domns = Namespace();
@warner

warner Nov 18, 2011

is "domns" short for "domains"? or.. DOM NameSpace? Maybe this should be "domNS" or "DOMns" or "DOM_ns"?

@Gozala

Gozala Nov 18, 2011

Owner

DOM NameSpace. I think it must be domNS but looked bit ugly to me. What about just dom ?

@warner

warner Nov 18, 2011

yeah, "dom" would be ok

+
+ function View(element) {
+ let view = Object.create(View.prototype);
+ domns(view).element = element;
+ // ....
+ }
+ View.prototype.destroy = function destroy() {
+ let { element } = domns(this);
+ element.parentNode.removeChild(element);
+ // ...
+ };
+ // ...
+ exports.View = View;
+
+Also, multiple namespaces can be used with one object:
@warner

warner Nov 18, 2011

it isn't completely obvious here that multiple namespaces are involved. I'm guessing that it's the View object that holds the second one? It might help to add a few comments to that effect..

+
+ // ./widget.js
+
+ let { Cu } = require('chrome');
+ let { Namespace } = require('api-utils/namespace');
+ let { View } = require('./view');
@warner

warner Nov 18, 2011

like here..

let { View } = require('./view'); // View has an internal Namespace object for its own purposes

@Gozala

Gozala Nov 18, 2011

Owner

view was defined above actually, but probably I could highlight that in comment.

+
+ let ns = Namespace();
@warner

warner Nov 18, 2011

or here:

let ns = Namespace(); // note: this is completely independent from View's internal Namespace object

+
+ function Widget(options) {
+ let { element, contentScript } = options;
+ let widget = Object.create(Widget.prototype);
+ View.call(widget, options.element);
+ ns(widget).sandbox = Cu.Sandbox(element.ownerDocument.defaultView);
+ // ...
+ }
+ Widget.prototype = Object.create(View.prototype);
+ Widget.prototype.postMessage = function postMessage(message) {
+ let { sandbox } = ns(this);
+ sandbox.postMessage(JSON.stringify(JSON.parse(message)));
+ ...
+ };
+ Widget.prototype.destroy = function destroy() {
+ View.prototype.destroy.call(this);
+ // ...
+ delete ns(this).sandbox;
+ };
+ exports.Widget = Widget;
+
+In addition access to the namespace can be shared by just handing them a
@warner

warner Nov 18, 2011

small fix: maybe use "can be shared with other code by just handing them..". The phrase is a bit awkward when it references "them" without introducing who "they" are first.

+namespace accessor function.
+
+ let { domns } = require('./view');
+ Widget.prototype.setInnerHTML = function setInnerHTML(html) {
+ domns(this).element.innerHTML = String(html);
+ };

0 comments on commit 550e74d

Please sign in to comment.