diff --git a/.gitignore b/.gitignore index 684ceaf..2315d24 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,4 @@ clouds.yaml # Doc build doc/build +doc/source/jsdoc diff --git a/doc/source/index.rst b/doc/source/index.rst index 54295b7..75d0a5d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,6 +15,7 @@ Topics :maxdepth: 2 getting_started + reference_documentation dev_get_started specs diff --git a/doc/source/reference_documentation.rst b/doc/source/reference_documentation.rst new file mode 100644 index 0000000..a7a1f20 --- /dev/null +++ b/doc/source/reference_documentation.rst @@ -0,0 +1,11 @@ +======================= +Reference Documentation +======================= + +Below you will find reference documentation for individual components of the JavaScript SDK. For +detailed, method-specific documentation, select the appropriate method below. + +.. toctree:: + :maxdepth: 2 + + jsdoc/Keystone diff --git a/package.json b/package.json index a650731..50dcfb9 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "lint": "eslint ./", "prepublish": "nsp check; npm run build", "build": "babel src -d dist && webpack", - "docs": "(cd ./doc && make html)" + "docs": "npm run jsdoc; (cd ./doc && make html)", + "jsdoc": "jsdoc -t node_modules/jsdoc-sphinx/template -d ./doc/source/jsdoc ./src" }, "repository": { "type": "git", @@ -45,6 +46,8 @@ "jasmine": "^2.4.1", "jasmine-core": "^2.4.1", "js-yaml": "^3.6.1", + "jsdoc": "^3.4.0", + "jsdoc-sphinx": "0.0.6", "json-loader": "^0.5.4", "karma": "^1.1.1", "karma-chrome-launcher": "^1.0.1", diff --git a/src/keystone.js b/src/keystone.js index 54f628d..a16c74f 100644 --- a/src/keystone.js +++ b/src/keystone.js @@ -3,7 +3,8 @@ import Http from './util/http'; /** * A list of all supported versions. Please keep this array sorted by most recent. * - * @type {Array} An array of version instances. + * @type {Array} + * @ignore */ const supportedKeystoneVersions = [ 'v3.7' @@ -11,6 +12,16 @@ const supportedKeystoneVersions = [ export default class Keystone { + /** + * This class provides direct, idempotent, low-level access to the Keystone API of a specific + * cloud. The constructor requires that you provide a configuration object for a specific + * cloud, formatted as per the os-client-config specification of clouds.yaml. An important + * difference is that it does not accept the entire clouds.yaml structure, only the subsection + * that refers to a specific cloud. + * + * @param {{}} cloudConfig The configuration object for a specific cloud. + * @see http://docs.openstack.org/developer/os-client-config/#site-specific-file-locations + */ constructor (cloudConfig) { // Sanity checks. if (!cloudConfig) { @@ -29,6 +40,7 @@ export default class Keystone { * @param {string} path A string representing the dot notation of a config path to read. * @private * @returns {String} The value found in the config, or null. + * @ignore */ _safeConfigGet (path) { let segments = path.split('.');