Add @module docs. Remove browser-build.sh

Add @links for HTML output. Replace browser-build.sh with inline commands in package.json so building will work on non-unix machines. Update README.
2026-01-03 23:22:30 +03:00 · 2015-06-04 16:34:00 +01:00
parent 31ffdf8a37
commit 7ab3e25218
9 changed files with 63 additions and 75 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ node_modules
 build/Release
 coverage
 lib-cov
+dist/browser-matrix-dev.js
--- a/README.rst
+++ b/README.rst
@@ -48,18 +48,12 @@ Building

 To build a browser version from scratch when developing::

- $ ./browser-build.sh
+ $ npm run build


 To constantly do builds when files are modified (using ``watchify``)::

- $ npm run watch-js
-
-
-To do a "release" build (``version`` is added to the filename)::
-
- $ npm run build-js
-
+ $ npm run watch

 API
 ===
--- a/browser-build.sh
+++ b/browser-build.sh
@@ -1,9 +0,0 @@
-#!/bin/bash
-if [ "$1" == "-w" ]
-then
-    watchify browser-index.js -o dist/browser-matrix-dev.js -v
-else
-    npm_package_version=${npm_package_version:="dev"}
-    echo "Building version '$npm_package_version' to /dist"
-    browserify browser-index.js -o dist/browser-matrix-$npm_package_version.js
-fi
--- a/dist/browser-matrix-dev.js
+++ b/dist/browser-matrix-dev.js
@@ -1,5 +1,10 @@
 (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){
 "use strict";
+/**
+ * This is an internal module. See {@link MatrixClient} for the public class.
+ * @module client
+ */
+
 var httpApi = require("./http-api");
 var MatrixEvent = require("./models/event").MatrixEvent;
 var utils = require("./utils");
@@ -7,8 +12,9 @@ var utils = require("./utils");
 // TODO:
 // Internal: rate limiting

-/*
+/**
 * Construct a Matrix Client.
+ * @constructor
 * @param {Object} opts The configuration options for this client.
 * @param {string} opts.baseUrl Required. The base URL to the client-server HTTP API.
 * @param {Function} opts.request Required. The function to invoke for HTTP requests.
@@ -17,7 +23,7 @@ var utils = require("./utils");
 * @param {string} opts.userId The user ID for this user.
 * @param {Object} opts.store The data store to use. See {@link store/memory}.
 */
-function MatrixClient(opts) {
+module.exports.MatrixClient = function MatrixClient(opts) {
    utils.checkObjectHasKeys(opts, ["baseUrl", "request"]);
    utils.checkObjectHasNoAdditionalKeys(opts,
        ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"]
@@ -38,8 +44,8 @@ function MatrixClient(opts) {
        userId: (opts.userId || null)
    };
    this._http = new httpApi.MatrixHttpApi(httpOpts);
-}
-MatrixClient.prototype = {
+};
+module.exports.MatrixClient.prototype = {

    // Room operations
    // ===============
@@ -707,13 +713,12 @@ MatrixClient.prototype = {
    },
 };

-/**
- * The high-level Matrix Client class.
- */
-module.exports = MatrixClient;  // expose the class
-
 },{"./http-api":2,"./models/event":4,"./utils":6}],2:[function(require,module,exports){
 "use strict";
+/**
+ * This is an internal module. See {@link MatrixHttpApi} for the public class.
+ * @module http-api
+ */

 var utils = require("./utils");

@@ -730,7 +735,7 @@ TODO:
 module.exports.PREFIX_V1 = "/_matrix/client/api/v1";

 /**
- * A constant representing the URI path for version 2 Alpha of the Client-Server
+ * A constant representing the URI path for version 2 alpha of the Client-Server
 * HTTP API.
 */
 module.exports.PREFIX_V2_ALPHA_PREFIX = "/_matrix/client/v2_alpha";
@@ -755,12 +760,12 @@ var HEADERS = {
 * @param {string} opts.accessToken The access_token to send with requests. Can be
 * null to not send an access token.
 */
-function MatrixHttpApi(opts) {
+module.exports.MatrixHttpApi = function MatrixHttpApi(opts) {
    utils.checkObjectHasKeys(opts, ["baseUrl", "request", "prefix"]);
    this.opts = opts;
-}
+};

-MatrixHttpApi.prototype = {
+module.exports.MatrixHttpApi.prototype = {

    // URI functions
    // =============
@@ -908,24 +913,17 @@ var requestCallback = function(userDefinedCallback) {
    };
 };

-
-
-/**
- * The Matrix HTTP API class.
- */
-module.exports.MatrixHttpApi = MatrixHttpApi;
-
 },{"./utils":6}],3:[function(require,module,exports){
 "use strict";

-/** The Matrix Event class */
+/** The Matrix Event class. */
 module.exports.MatrixEvent = require("./models/event").MatrixEvent;
 /** An in-memory store for the SDK */
 module.exports.MatrixInMemoryStore = require("./store/memory");
-/** The raw HTTP API */
-module.exports.MatrixHttpApi = require("./http-api");
-/** The managed client class */
-module.exports.MatrixClient = require("./client");
+/** The {@link module:http-api.MatrixHttpApi|MatrixHttpApi} class. */
+module.exports.MatrixHttpApi = require("./http-api").MatrixHttpApi;
+/** The {@link module:client.MatrixClient|MatrixClient} class. */
+module.exports.MatrixClient = require("./client").MatrixClient;

 // expose the underlying request object so different environments can use
 // different request libs (e.g. request or browser-request)
@@ -939,8 +937,8 @@ module.exports.request = function(r) {
 };

 /**
- * Construct a Matrix Client. Identical to {@link client/MatrixClient} except
- * the 'request' option is already specified.
+ * Construct a Matrix Client. Identical to {@link module:client.MatrixClient}
+ * except the 'request' option is already specified.
 * @param {(Object|string)} opts The configuration options for this client. If
 * this is a string, it is assumed to be the base URL.
 * @param {string} opts.baseUrl The base URL to the client-server HTTP API.
@@ -1166,7 +1164,10 @@ module.exports = MatrixInMemoryStore;

 },{}],6:[function(require,module,exports){
 "use strict";
-
+/**
+ * This is an internal module.
+ * @module utils
+ */

 /**
 * Encode a dictionary of query parameters.
--- a/lib/client.js
+++ b/lib/client.js
@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * This is an internal module. See {@link MatrixClient} for the public class.
+ * @module client
+ */
+
 var httpApi = require("./http-api");
 var MatrixEvent = require("./models/event").MatrixEvent;
 var utils = require("./utils");
@@ -6,8 +11,9 @@ var utils = require("./utils");
 // TODO:
 // Internal: rate limiting

-/*
+/**
 * Construct a Matrix Client.
+ * @constructor
 * @param {Object} opts The configuration options for this client.
 * @param {string} opts.baseUrl Required. The base URL to the client-server HTTP API.
 * @param {Function} opts.request Required. The function to invoke for HTTP requests.
@@ -16,7 +22,7 @@ var utils = require("./utils");
 * @param {string} opts.userId The user ID for this user.
 * @param {Object} opts.store The data store to use. See {@link store/memory}.
 */
-function MatrixClient(opts) {
+module.exports.MatrixClient = function MatrixClient(opts) {
    utils.checkObjectHasKeys(opts, ["baseUrl", "request"]);
    utils.checkObjectHasNoAdditionalKeys(opts,
        ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"]
@@ -37,8 +43,8 @@ function MatrixClient(opts) {
        userId: (opts.userId || null)
    };
    this._http = new httpApi.MatrixHttpApi(httpOpts);
-}
-MatrixClient.prototype = {
+};
+module.exports.MatrixClient.prototype = {

    // Room operations
    // ===============
@@ -705,8 +711,3 @@ MatrixClient.prototype = {
        this.clientRunning = false;
    },
 };
-
-/**
- * The high-level Matrix Client class.
- */
-module.exports = MatrixClient;  // expose the class
--- a/lib/http-api.js
+++ b/lib/http-api.js
@@ -1,4 +1,8 @@
 "use strict";
+/**
+ * This is an internal module. See {@link MatrixHttpApi} for the public class.
+ * @module http-api
+ */

 var utils = require("./utils");

@@ -15,7 +19,7 @@ TODO:
 module.exports.PREFIX_V1 = "/_matrix/client/api/v1";

 /**
- * A constant representing the URI path for version 2 Alpha of the Client-Server
+ * A constant representing the URI path for version 2 alpha of the Client-Server
 * HTTP API.
 */
 module.exports.PREFIX_V2_ALPHA_PREFIX = "/_matrix/client/v2_alpha";
@@ -40,12 +44,12 @@ var HEADERS = {
 * @param {string} opts.accessToken The access_token to send with requests. Can be
 * null to not send an access token.
 */
-function MatrixHttpApi(opts) {
+module.exports.MatrixHttpApi = function MatrixHttpApi(opts) {
    utils.checkObjectHasKeys(opts, ["baseUrl", "request", "prefix"]);
    this.opts = opts;
-}
+};

-MatrixHttpApi.prototype = {
+module.exports.MatrixHttpApi.prototype = {

    // URI functions
    // =============
@@ -192,10 +196,3 @@ var requestCallback = function(userDefinedCallback) {
        }
    };
 };
-
-
-
-/**
- * The Matrix HTTP API class.
- */
-module.exports.MatrixHttpApi = MatrixHttpApi;
--- a/lib/matrix.js
+++ b/lib/matrix.js
@@ -1,13 +1,13 @@
 "use strict";

-/** The Matrix Event class */
+/** The Matrix Event class. */
 module.exports.MatrixEvent = require("./models/event").MatrixEvent;
 /** An in-memory store for the SDK */
 module.exports.MatrixInMemoryStore = require("./store/memory");
-/** The raw HTTP API */
-module.exports.MatrixHttpApi = require("./http-api");
-/** The managed client class */
-module.exports.MatrixClient = require("./client");
+/** The {@link module:http-api.MatrixHttpApi|MatrixHttpApi} class. */
+module.exports.MatrixHttpApi = require("./http-api").MatrixHttpApi;
+/** The {@link module:client.MatrixClient|MatrixClient} class. */
+module.exports.MatrixClient = require("./client").MatrixClient;

 // expose the underlying request object so different environments can use
 // different request libs (e.g. request or browser-request)
@@ -21,8 +21,8 @@ module.exports.request = function(r) {
 };

 /**
- * Construct a Matrix Client. Identical to {@link client/MatrixClient} except
- * the 'request' option is already specified.
+ * Construct a Matrix Client. Identical to {@link module:client.MatrixClient}
+ * except the 'request' option is already specified.
 * @param {(Object|string)} opts The configuration options for this client. If
 * this is a string, it is assumed to be the base URL.
 * @param {string} opts.baseUrl The base URL to the client-server HTTP API.
--- a/lib/utils.js
+++ b/lib/utils.js
@@ -1,5 +1,8 @@
 "use strict";
-
+/**
+ * This is an internal module.
+ * @module utils
+ */

 /**
 * Encode a dictionary of query parameters.
--- a/package.json
+++ b/package.json
@@ -5,8 +5,8 @@
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
-    "build-js": "./browser-build.sh",
-    "watch-js": "./browser-build.sh -w"
+    "build": "browserify browser-index.js -o dist/browser-matrix-dev.js",
+    "watch": "watchify browser-index.js -o dist/browser-matrix-dev.js -v"
  },
  "repository": {
    "url": "https://github.com/matrix-org/matrix-js-sdk"