Merge pull request #282 from auth0/added-pagination-docs

Added Pagination Docs
auth0 · Jul 16, 2018 · 529f8f8 · 529f8f8
2 parents 71c77f7 + 7027f2d
commit 529f8f8
Show file tree

Hide file tree

Showing 7 changed files with 160 additions and 48 deletions.
diff --git a/src/management/ClientGrantsManager.js b/src/management/ClientGrantsManager.js
@@ -82,12 +82,27 @@ utils.wrapPropertyMethod(ClientGrantsManager, 'create', 'resource.create');
  * @method    getAll
  * @memberOf  module:management.ClientGrantsManager.prototype
  *
- * @example
- * management.clientGrants.getAll(function (err, grants) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ *
+ * management.clientGrants.getAll(params, function (err, grants) {
  *   console.log(grants.length);
  * });
  *
- * @param   {Function}  [cb]    Callback function.
+ * @param   {Object}    [params]          Client Grants parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */

diff --git a/src/management/ClientsManager.js b/src/management/ClientsManager.js
@@ -95,16 +95,16 @@ utils.wrapPropertyMethod(ClientsManager, 'create', 'resource.create');
  * // Pagination settings.
  * var params = {
  *   per_page: 10,
- *   page: 2
+ *   page: 0
  * };
  *
- * management.clients.getAll(function (err, clients) {
+ * management.clients.getAll(params, function (err, clients) {
  *   console.log(clients.length);
  * });
  *
- * @param   {Object}    [params]          Clients params.
- * @param   {Number}    [params.per_page] Number of clients per page.
- * @param   {Number}    [params.page]     Page number.
+ * @param   {Object}    [params]          Clients parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
  * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}

diff --git a/src/management/ConnectionsManager.js b/src/management/ConnectionsManager.js
@@ -89,16 +89,16 @@ utils.wrapPropertyMethod(ConnectionsManager, 'create', 'resource.create');
  * // Pagination settings.
  * var params = {
  *   per_page: 10,
- *   page: 2
+ *   page: 0
  * };
  *
- * management.connections.getAll(function (err, connections) {
+ * management.connections.getAll(params, function (err, connections) {
  *   console.log(connections.length);
  * });
  *
  * @param   {Object}    [params]          Connections params.
- * @param   {Number}    [params.per_page] Number of connections per page.
- * @param   {Number}    [params.page]     Page number.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
  * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}

diff --git a/src/management/ResourceServersManager.js b/src/management/ResourceServersManager.js
@@ -86,12 +86,26 @@ utils.wrapPropertyMethod(ResourceServersManager, 'create', 'resource.create');
  * @method    getAll
  * @memberOf  module:management.ResourceServersManager.prototype
  *
- * @example
- * management.resourceServers.getAll(function (err, resourceServers) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.resourceServers.getAll(params, function (err, resourceServers) {
  *   console.log(resourceServers.length);
  * });
  *
- * @param   {Function}  [cb]    Callback function.
+ * @param   {Object}    [params]          Resource Servers parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */

diff --git a/src/management/RulesManager.js b/src/management/RulesManager.js
@@ -86,12 +86,26 @@ utils.wrapPropertyMethod(RulesManager, 'create', 'resource.create');
  * @method    getAll
  * @memberOf  module:management.RulesManager.prototype
  *
- * @example
- * management.rules.getAll(function (err, rules) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.rules.getAll(params, function (err, rules) {
  *   console.log(rules.length);
  * });
  *
- * @param   {Function}  [cb]     Callback function.
+ * @param   {Object}    [params]          Rules parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */

diff --git a/src/management/UsersManager.js b/src/management/UsersManager.js
@@ -151,16 +151,16 @@ UsersManager.prototype.create = function(data, cb) {
  * // Pagination settings.
  * var params = {
  *   per_page: 10,
- *   page: 2
+ *   page: 0
  * };
  *
- * management.users.getAll(function (err, users) {
+ * management.users.getAll(params, function (err, users) {
  *   console.log(users.length);
  * });
  *
  * @param   {Object}    [params]          Users params.
- * @param   {Number}    [params.per_page] Number of users per page.
- * @param   {Number}    [params.page]     Page number.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
  * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
@@ -538,8 +538,8 @@ UsersManager.prototype.unlink = function(params, cb) {
  *
  * @param   {Object}    params                Get logs data.
  * @param   {String}    params.id             User id.
- * @param   {Number}    params.per_page       Number of logs per page.
- * @param   {Number}    params.page           Page number.
+ * @param   {Number}    params.per_page       Number of results per page.
+ * @param   {Number}    params.page           Page number, zero indexed.
  * @param   {String}    params.sort           The field to use for sorting. Use field:order where order is 1 for ascending and -1 for descending. For example date:-1.
  * @param   {Boolean}   params.include_totals true if a query summary must be included in the result, false otherwise. Default false;
  * @param   {Function}  [cb]                  Callback function.

diff --git a/src/management/index.js b/src/management/index.js
@@ -291,13 +291,26 @@ ManagementClient.prototype.getClientInfo = function() {
  * @method    getConnections
  * @memberOf  module:management.ManagementClient.prototype
  *
- * @example
- * management.getConnections(function (err, connections) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.getConnections(params, function (err, connections) {
  *   console.log(connections.length);
  * });
  *
- * @param   {Object}    data     Connection data object.
- * @param   {Function}  [cb]     Callback function.
+ * @param   {Object}    [params]          Connections params.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */
@@ -389,7 +402,7 @@ utils.wrapPropertyMethod(ManagementClient, 'deleteConnection', 'connections.dele
  *   console.log(connection.name);  // 'newConnectionName'
  * });
  *
- * @param   {Object}    params        Conneciton parameters.
+ * @param   {Object}    params        Connection parameters.
  * @param   {String}    params.id     Connection ID.
  * @param   {Object}    data          Updated connection data.
  * @param   {Function}  [cb]          Callback function.
@@ -404,12 +417,26 @@ utils.wrapPropertyMethod(ManagementClient, 'updateConnection', 'connections.upda
  * @method    getClients
  * @memberOf  module:management.ManagementClient.prototype
  *
- * @example
- * management.getClients(function (err, clients) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.getClients(params, function (err, clients) {
  *   console.log(clients.length);
  * });
  *
- * @param   {Function}  [cb]    Callback function.
+ * @param   {Object}    [params]          Clients parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */
@@ -516,12 +543,26 @@ utils.wrapPropertyMethod(ManagementClient, 'deleteClient', 'clients.delete');
  * @method    getAll
  * @memberOf  module:management.ClientGrantsManager.prototype
  *
- * @example
- * management.clientGrants.getAll(function (err, grants) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.getClientGrants(params, function (err, grants) {
  *   console.log(grants.length);
  * });
  *
- * @param   {Function}  [cb]    Callback function.
+ * @param   {Object}    [params]          Client Grants parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */
@@ -677,12 +718,26 @@ utils.wrapPropertyMethod(ManagementClient, 'deleteDeviceCredential', 'deviceCred
  * @method    getRules
  * @memberOf  module:management.ManagementClient.prototype
  *
- * @example
- * management.getRules(function (err, rules) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.getRules(params, function (err, rules) {
  *   console.log(rules.length);
  * });
  *
- * @param   {Function}  [cb]     Callback function.
+ * @param   {Object}    [params]          Rules parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */
@@ -790,22 +845,23 @@ utils.wrapPropertyMethod(ManagementClient, 'updateRule', 'rules.update');
  *
  * @example <caption>
  *   This method takes an optional object as first argument that may be used to
- *   specify pagination settings and the search query.
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
  * </caption>
  *
  * // Pagination settings.
  * var params = {
  *   per_page: 10,
- *   page: 2
+ *   page: 0
  * };
  *
  * auth0.getUsers(params, function (err, users) {
  *   console.log(users.length);
  * });
  *
  * @param   {Object}    [params]          Users params.
- * @param   {Number}    [params.per_page] Number of users per page.
- * @param   {Number}    [params.page]     Page number.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
  * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
@@ -1147,8 +1203,8 @@ utils.wrapPropertyMethod(ManagementClient, 'linkUsers', 'users.link');
  *
  * @param   {Object}    params                Get logs data.
  * @param   {String}    params.id             User id.
- * @param   {Number}    params.per_page       Number of logs per page.
- * @param   {Number}    params.page           Page number.
+ * @param   {Number}    params.per_page       Number of results per page.
+ * @param   {Number}    params.page           Page number, zero indexed.
  * @param   {String}    params.sort           The field to use for sorting. Use field:order where order is 1 for ascending and -1 for descending. For example date:-1.
  * @param   {Boolean}   params.include_totals true if a query summary must be included in the result, false otherwise. Default false;
  * @param   {Function}  [cb]                  Callback function.
@@ -1617,13 +1673,26 @@ utils.wrapPropertyMethod(ManagementClient, 'createResourceServer', 'resourceServ
  * @method    getResourceServers
  * @memberOf  module:management.ManagementClient.prototype
  *
- * @example
- * management.getResourceServers(function (err, resourceServers) {
+ * @example <caption>
+ *   This method takes an optional object as first argument that may be used to
+ *   specify pagination settings. If pagination options are not present,
+ *   the first page of a limited number of results will be returned.
+ * </caption>
+ *
+ * // Pagination settings.
+ * var params = {
+ *   per_page: 10,
+ *   page: 0
+ * };
+ *
+ * management.getResourceServers(params, function (err, resourceServers) {
  *   console.log(resourceServers.length);
  * });
  *
- * @param   {Object}    data     Connection data object.
- * @param   {Function}  [cb]     Callback function.
+ * @param   {Object}    [params]          Resource Servers parameters.
+ * @param   {Number}    [params.per_page] Number of results per page.
+ * @param   {Number}    [params.page]     Page number, zero indexed.
+ * @param   {Function}  [cb]              Callback function.
  *
  * @return  {Promise|undefined}
  */