Bug 560980 - xul-app module needs documentation. r=atul, a0.7=myk (from bug 569708 comment 4)
authorDrew Willcoxon <adw@mozilla.com>
Mon, 23 Aug 2010 19:26:15 -0700
changeset 758 cc8e33ef9ff75e7ca23636b3bbd7f81353c1b41e
parent 757 01e59b9e7cbe8519bd91723a11a4462f02c2ba5b
child 759 9cc530cc79dcd8136f0c25d27f8ae4c60c874330
push id284
push userdwillcoxon@mozilla.com
push dateTue, 24 Aug 2010 02:26:44 +0000
reviewersatul
bugs560980, 569708
Bug 560980 - xul-app module needs documentation. r=atul, a0.7=myk (from bug 569708 comment 4)
packages/jetpack-core/docs/xul-app.md
new file mode 100644
--- /dev/null
+++ b/packages/jetpack-core/docs/xul-app.md
@@ -0,0 +1,80 @@
+<!-- contributed by Drew Willcoxon [adw@mozilla.com] -->
+
+The `xul-app` module provides facilities for introspecting the application on
+which your program is running.
+
+
+Properties
+----------
+
+With the exception of `ids`, each of these properties exposes the attribute of
+the same name on the [`nsIXULAppInfo`][nsIXULAppInfo] interface.  For more
+information, see the [MDC documentation][].
+
+[nsIXULAppInfo]: http://mxr.mozilla.org/mozilla-central/source/xpcom/system/nsIXULAppInfo.idl
+[MDC documentation]: https://developer.mozilla.org/en/nsIXULAppInfo
+
+<api name="ID">
+@property {string}
+  The GUID of the host application.  For example, for Firefox this value is
+  `"{ec8030f7-c20a-464f-9b0e-13a3a9e97384}"`.
+</api>
+
+<api name="name">
+@property {string}
+  The host application name.  For example, `"Firefox"`.
+</api>
+
+<api name="version">
+@property {string}
+  The host application version.
+</api>
+
+<api name="platformVersion">
+@property {string}
+  The Gecko/XULRunner platform version.
+</api>
+
+<api name="ids">
+@property {object}
+  A mapping of application names to their IDs.  For example,
+  `ids["Firefox"] == "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}"`.
+</api>
+
+
+Functions
+---------
+
+<api name="is">
+@function
+  Checks whether the host application is the given application.
+@param name {string}
+  A host application name.
+@returns {boolean}
+  True if the host application is `name` and false otherwise.
+</api>
+
+<api name="isOneOf">
+@function
+  Checks whether the host application is one of the given applications.
+@param names {array}
+  An array of host application names.
+@returns {boolean}
+  True if the host application is one of the `names` and false otherwise.
+</api>
+
+<api name="versionInRange">
+@function
+  Compares a given version to a version range.  See the [MDC documentation](https://developer.mozilla.org/en/Toolkit_version_format#Comparing_versions)
+  for details on version comparisons.
+@param version {string}
+  The version to compare.
+@param lowInclusive {string}
+  The lower bound of the version range to compare.  The range includes this
+  bound.
+@param highExclusive {string}
+  The upper bound of the version range to compare.  The range does not include
+  this bound.
+@returns {boolean}
+  True if `version` falls in the given range and false otherwise.
+</api>