Docstring fixes and additions (#848)

kevinthecheung · web-flow · commit bbd92f1bcf80 · 2020-04-16T09:46:32.000-07:00
* Docstring fixes and additions

* A few edits
diff --git a/src/index.d.ts b/src/index.d.ts
@@ -272,11 +272,11 @@ declare namespace admin {
   function messaging(app?: admin.app.App): admin.messaging.Messaging;
 
   /**
-   * Gets the {@link admin.ml.MachineLearning `MachineLearning`} service for the
+   * Gets the {@link admin.machineLearning.MachineLearning `MachineLearning`} service for the
    * default app or a given app.
    *
    * `admin.machineLearning()` can be called with no arguments to access the
-   * default app's {@link admin.machineLearing.MachineLearning
+   * default app's {@link admin.machineLearning.MachineLearning
     * `MachineLearning`} service or as `admin.machineLearning(app)` to access
     * the {@link admin.machineLearning.MachineLearning `MachineLearning`}
     * service associated with a specific app.
@@ -5208,52 +5208,124 @@ declare namespace admin.machineLearning {
    * Interface representing options for listing Models.
    */
   interface ListModelsOptions {
+    /**
+     * An expression that specifies how to filter the results.
+     *
+     * Examples:
+     *
+     * ```
+     * display_name = your_model
+     * display_name : experimental_*
+     * tags: face_detector AND tags: experimental
+     * state.published = true
+     * ```
+     *
+     * See https://firebase.google.com/docs/ml-kit/manage-hosted-models#list_your_projects_models
+     */
     filter?: string;
+
+    /** The number of results to return in each page. */
     pageSize?: number;
+
+    /** A token that specifies the result page to return. */
     pageToken?: string;
   }
 
   /** Response object for a listModels operation. */
   interface ListModelsResult {
+    /** A list of models in your project. */
     readonly models: Model[];
+
+    /** 
+     * A token you can use to retrieve the next page of results. If null, the
+     * current page is the final page.
+     */
     readonly pageToken?: string;
   }
 
   /**
-   * A TFLite Model output object
+   * A TensorFlow Lite Model output object
    */
   interface TFLiteModel {
+    /** The size of the model. */
     readonly sizeBytes: number;
 
+    /** The URI from which the model was originally provided to Firebase. */
     readonly gcsTfliteUri?: string;
   }
 
   /**
    * A Firebase ML Model input object
    */
   interface ModelOptions {
+    /** A name for the model. This is the name you use from your app to load the model. */
     displayName?: string;
+
+    /** Tags for easier model management. */
     tags?: string[];
 
+    /** 
+     * An object containing the URI of the model in Cloud Storage.
+     *
+     * Example: `tfliteModel: { gcsTfliteUri: 'gs://your-bucket/your-model.tflite' }`
+     */
     tfliteModel?: {gcsTfliteUri: string;};
   }
 
   /**
    * A Firebase ML Model output object
    */
   interface Model {
+    /** The ID of the model. */
     readonly modelId: string;
+
+    /** The model's name. This is the name you use from your app to load the model. */
     readonly displayName: string;
+
+    /** The model's tags. */
     readonly tags?: string[];
+
+    /** The timestamp of the model's creation. */
     readonly createTime: string;
+
+    /** The timestamp of the model's most recent update. */
     readonly updateTime: string;
+
+    /** Error message when model validation fails. */
     readonly validationError?: string;
+
+    /** True if the model is published. */
     readonly published: boolean;
+
+    /**
+     * The ETag identifier of the current version of the model. This value
+     * changes whenever you update any of the model's properties.
+     */
     readonly etag: string;
+
+    /**
+     * The hash of the model's `tflite` file. This value changes only when
+     * you upload a new TensorFlow Lite model.
+     */
     readonly modelHash?: string;
+
+    /**
+     * True if the model is locked by a server-side operation. You can't make
+     * changes to a locked model. See {@link waitForUnlocked `waitForUnlocked()`}.
+     */
     readonly locked: boolean;
+
+    /** 
+     * Wait for the model to be unlocked.
+     *
+     * @param {number} maxTimeSeconds The maximum time in seconds to wait.
+     *
+     * @return {Promise<void>} A promise that resolves when the model is unlocked
+     *   or the maximum wait time has passed.
+     */
     waitForUnlocked(maxTimeSeconds?: number): Promise<void>;
 
+    /** Metadata about the model's TensorFlow Lite model file. */
     readonly tfliteModel?: TFLiteModel;
   }
 
@@ -5264,6 +5336,10 @@ declare namespace admin.machineLearning {
    * [`admin.machineLearning()`](admin.machineLearning#machineLearning).
    */
   interface MachineLearning {
+    /**
+     *  The {@link admin.app.App} associated with the current `MachineLearning`
+     *  service instance.
+     */
     app: admin.app.App;
 
     /**
@@ -5278,7 +5354,7 @@ declare namespace admin.machineLearning {
     /**
      * Updates a model in Firebase ML.
      *
-     * @param {string} modelId The id of the model to update.
+     * @param {string} modelId The ID of the model to update.
      * @param {ModelOptions} model The model fields to update.
      *
      * @return {Promise<Model>} A Promise fulfilled with the updated model.
@@ -5288,7 +5364,7 @@ declare namespace admin.machineLearning {
     /**
      * Publishes a model in Firebase ML.
      *
-     * @param {string} modelId The id of the model to publish.
+     * @param {string} modelId The ID of the model to publish.
      *
      * @return {Promise<Model>} A Promise fulfilled with the published model.
      */
@@ -5297,7 +5373,7 @@ declare namespace admin.machineLearning {
     /**
      * Unpublishes a model in Firebase ML.
      *
-     * @param {string} modelId The id of the model to unpublish.
+     * @param {string} modelId The ID of the model to unpublish.
      *
      * @return {Promise<Model>} A Promise fulfilled with the unpublished model.
      */
@@ -5306,9 +5382,9 @@ declare namespace admin.machineLearning {
     /**
      * Gets a model from Firebase ML.
      *
-     * @param {string} modelId The id of the model to get.
+     * @param {string} modelId The ID of the model to get.
      *
-     * @return {Promise<Model>} A Promise fulfilled with the unpublished model.
+     * @return {Promise<Model>} A Promise fulfilled with the model object.
      */
     getModel(modelId: string): Promise<Model>;
 
@@ -5317,17 +5393,17 @@ declare namespace admin.machineLearning {
      *
      * @param {ListModelsOptions} options The listing options.
      *
-     * @return {Promise<{models: Model[], pageToken?: string}>} A promise that
+     * @return {Promise<ListModelsResult>} A promise that
      *     resolves with the current (filtered) list of models and the next page
      *     token. For the last page, an empty list of models and no page token
-     * are returned.
+     *     are returned.
      */
     listModels(options?: ListModelsOptions): Promise<ListModelsResult>;
 
     /**
      * Deletes a model from Firebase ML.
      *
-     * @param {string} modelId The id of the model to delete.
+     * @param {string} modelId The ID of the model to delete.
      */
     deleteModel(modelId: string): Promise<void>;
   }
