version 3.0.0 API Docs (#4943)

* Adds documentation and docs generation upon merge * nits
2018-08-09 16:20:13 -04:00
parent 457d51a972
commit 0571675fcd
10 changed files with 465 additions and 3 deletions
--- a/src/cloud-code/Parse.Cloud.js
+++ b/src/cloud-code/Parse.Cloud.js
@@ -8,40 +8,202 @@ function getClassName(parseClass) {
  return parseClass;
 }

+/** @namespace
+ * @name Parse
+ * @description The Parse SDK.
+ *  see [api docs](https://docs.parseplatform.org/js/api) and [guide](https://docs.parseplatform.org/js/guide)
+ */
+
+/** @namespace
+ * @name Parse.Cloud
+ * @memberof Parse
+ * @description The Parse Cloud Code SDK.
+ */
+
 var ParseCloud = {};
+/**
+ * Defines a Cloud Function.
+ *
+ * **Available in Cloud Code only.**
+
+ * @static
+ * @memberof Parse.Cloud
+ * @param {String} name The name of the Cloud Function
+ * @param {Function} data The Cloud Function to register. This function can be an async function and should take one parameter a {@link Parse.Cloud.FunctionRequest}.
+ */
 ParseCloud.define = function(functionName, handler, validationHandler) {
  triggers.addFunction(functionName, handler, validationHandler, Parse.applicationId);
 };

+/**
+ * Defines a Background Job.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * @method job
+ * @name Parse.Cloud.job
+ * @param {String} name The name of the Background Job
+ * @param {Function} func The Background Job to register. This function can be async should take a single parameters a {@link Parse.Cloud.JobRequest}
+ *
+ */
 ParseCloud.job = function(functionName, handler) {
  triggers.addJob(functionName, handler, Parse.applicationId);
 };

+/**
+ *
+ * Registers a before save function.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * If you want to use beforeSave for a predefined class in the Parse JavaScript SDK (e.g. {@link Parse.User}), you should pass the class itself and not the String for arg1.
+ *
+ * ```
+ * Parse.Cloud.beforeSave('MyCustomClass', (request) => {
+ *   // code here
+ * })
+ *
+ * Parse.Cloud.beforeSave(Parse.User, (request) => {
+ *   // code here
+ * })
+ * ```
+ *
+ * @method beforeSave
+ * @name Parse.Cloud.beforeSave
+ * @param {(String|Parse.Object)} arg1 The Parse.Object subclass to register the after save function for. This can instead be a String that is the className of the subclass.
+ * @param {Function} func The function to run before a save. This function can be async and should take one parameter a {@link Parse.Cloud.TriggerRequest};
+ */
 ParseCloud.beforeSave = function(parseClass, handler) {
  var className = getClassName(parseClass);
  triggers.addTrigger(triggers.Types.beforeSave, className, handler, Parse.applicationId);
 };

+/**
+ * Registers a before delete function.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * If you want to use beforeDelete for a predefined class in the Parse JavaScript SDK (e.g. {@link Parse.User}), you should pass the class itself and not the String for arg1.
+ * ```
+ * Parse.Cloud.beforeDelete('MyCustomClass', (request) => {
+ *   // code here
+ * })
+ *
+ * Parse.Cloud.beforeDelete(Parse.User, (request) => {
+ *   // code here
+ * })
+ *```
+ *
+ * @method beforeDelete
+ * @name Parse.Cloud.beforeDelete
+ * @param {(String|Parse.Object)} arg1 The Parse.Object subclass to register the before delete function for. This can instead be a String that is the className of the subclass.
+ * @param {Function} func The function to run before a delete. This function can be async and should take one parameter, a {@link Parse.Cloud.TriggerRequest}.
+ */
 ParseCloud.beforeDelete = function(parseClass, handler) {
  var className = getClassName(parseClass);
  triggers.addTrigger(triggers.Types.beforeDelete, className, handler, Parse.applicationId);
 };

+/**
+ * Registers an after save function.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * If you want to use afterSave for a predefined class in the Parse JavaScript SDK (e.g. {@link Parse.User}), you should pass the class itself and not the String for arg1.
+ *
+ * ```
+ * Parse.Cloud.afterSave('MyCustomClass', async function(request) {
+ *   // code here
+ * })
+ *
+ * Parse.Cloud.afterSave(Parse.User, async function(request) {
+ *   // code here
+ * })
+ * ```
+ *
+ * @method afterSave
+ * @name Parse.Cloud.afterSave
+ * @param {(String|Parse.Object)} arg1 The Parse.Object subclass to register the after save function for. This can instead be a String that is the className of the subclass.
+ * @param {Function} func The function to run after a save. This function can be an async function and should take just one parameter, {@link Parse.Cloud.TriggerRequest}.
+ */
 ParseCloud.afterSave = function(parseClass, handler) {
  var className = getClassName(parseClass);
  triggers.addTrigger(triggers.Types.afterSave, className, handler, Parse.applicationId);
 };

+/**
+ * Registers an after delete function.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * If you want to use afterDelete for a predefined class in the Parse JavaScript SDK (e.g. {@link Parse.User}), you should pass the class itself and not the String for arg1.
+ * ```
+ * Parse.Cloud.afterDelete('MyCustomClass', async (request) => {
+ *   // code here
+ * })
+ *
+ * Parse.Cloud.afterDelete(Parse.User, async (request) => {
+ *   // code here
+ * })
+ *```
+ *
+ * @method afterDelete
+ * @name Parse.Cloud.afterDelete
+ * @param {(String|Parse.Object)} arg1 The Parse.Object subclass to register the after delete function for. This can instead be a String that is the className of the subclass.
+ * @param {Function} func The function to run after a delete. This function can be async and should take just one parameter, {@link Parse.Cloud.TriggerRequest}.
+ */
 ParseCloud.afterDelete = function(parseClass, handler) {
  var className = getClassName(parseClass);
  triggers.addTrigger(triggers.Types.afterDelete, className, handler, Parse.applicationId);
 };

+/**
+ * Registers a before find function.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * If you want to use beforeFind for a predefined class in the Parse JavaScript SDK (e.g. {@link Parse.User}), you should pass the class itself and not the String for arg1.
+ * ```
+ * Parse.Cloud.beforeFind('MyCustomClass', async (request) => {
+ *   // code here
+ * })
+ *
+ * Parse.Cloud.beforeFind(Parse.User, async (request) => {
+ *   // code here
+ * })
+ *```
+ *
+ * @method beforeFind
+ * @name Parse.Cloud.beforeFind
+ * @param {(String|Parse.Object)} arg1 The Parse.Object subclass to register the before find function for. This can instead be a String that is the className of the subclass.
+ * @param {Function} func The function to run before a find. This function can be async and should take just one parameter, {@link Parse.Cloud.BeforeFindRequest}.
+ */
 ParseCloud.beforeFind = function(parseClass, handler) {
  var className = getClassName(parseClass);
  triggers.addTrigger(triggers.Types.beforeFind, className, handler, Parse.applicationId);
 };

+/**
+ * Registers an after find function.
+ *
+ * **Available in Cloud Code only.**
+ *
+ * If you want to use afterFind for a predefined class in the Parse JavaScript SDK (e.g. {@link Parse.User}), you should pass the class itself and not the String for arg1.
+ * ```
+ * Parse.Cloud.afterFind('MyCustomClass', async (request) => {
+ *   // code here
+ * })
+ *
+ * Parse.Cloud.afterFind(Parse.User, async (request) => {
+ *   // code here
+ * })
+ *```
+ *
+ * @method afterFind
+ * @name Parse.Cloud.afterFind
+ * @param {(String|Parse.Object)} arg1 The Parse.Object subclass to register the after find function for. This can instead be a String that is the className of the subclass.
+ * @param {Function} func The function to run before a find. This function can be async and should take just one parameter, {@link Parse.Cloud.AfterFindRequest}.
+ */
 ParseCloud.afterFind = function(parseClass, handler) {
  const className = getClassName(parseClass);
  triggers.addTrigger(triggers.Types.afterFind, className, handler, Parse.applicationId);
@@ -63,3 +225,56 @@ ParseCloud.useMasterKey = () => {
 ParseCloud.httpRequest = require("./httpRequest");

 module.exports = ParseCloud;
+
+/**
+ * @typedef Parse.Cloud.TriggerRequest
+ * @property {String} installationId If set, the installationId triggering the request.
+ * @property {Boolean} master If true, means the master key was used.
+ * @property {Parse.User} user If set, the user that made the request.
+ * @property {Parse.Object} object The object triggering the hook.
+ * @property {String} ip The IP address of the client making the request.
+ * @property {Object} headers The original HTTP headers for the request.
+ * @property {String} triggerName The name of the trigger (`beforeSave`, `afterSave`, ...)
+ * @property {Object} log The current logger inside Parse Server.
+ * @property {Parse.Object} original If set, the object, as currently stored.
+ */
+
+/**
+ * @typedef Parse.Cloud.BeforeFindRequest
+ * @property {String} installationId If set, the installationId triggering the request.
+ * @property {Boolean} master If true, means the master key was used.
+ * @property {Parse.User} user If set, the user that made the request.
+ * @property {Parse.Query} query The query triggering the hook.
+ * @property {String} ip The IP address of the client making the request.
+ * @property {Object} headers The original HTTP headers for the request.
+ * @property {String} triggerName The name of the trigger (`beforeSave`, `afterSave`, ...)
+ * @property {Object} log The current logger inside Parse Server.
+ * @property {Boolean} isGet wether the query a `get` or a `find`
+ */
+
+/**
+ * @typedef Parse.Cloud.AfterFindRequest
+ * @property {String} installationId If set, the installationId triggering the request.
+ * @property {Boolean} master If true, means the master key was used.
+ * @property {Parse.User} user If set, the user that made the request.
+ * @property {Parse.Query} query The query triggering the hook.
+ * @property {Array<Parse.Object>} results The results the query yielded.
+ * @property {String} ip The IP address of the client making the request.
+ * @property {Object} headers The original HTTP headers for the request.
+ * @property {String} triggerName The name of the trigger (`beforeSave`, `afterSave`, ...)
+ * @property {Object} log The current logger inside Parse Server.
+ */
+
+/**
+ * @typedef Parse.Cloud.FunctionRequest
+ * @property {String} installationId If set, the installationId triggering the request.
+ * @property {Boolean} master If true, means the master key was used.
+ * @property {Parse.User} user If set, the user that made the request.
+ * @property {Object} params The params passed to the cloud function.
+ */
+
+/**
+ * @typedef Parse.Cloud.JobRequest
+ * @property {Object} params The params passed to the background job.
+ * @property {function} message If message is called with a string argument, will update the current message to be stored in the job status.
+ */