Script.getExternalPath() and related JSDoc

libraries/networking/src/ExternalResource.h

@@ -42,28 +42,43 @@ public:
     static ExternalResource* getInstance();
     ~ExternalResource(){};
 
-    /**
-     * Bucket from which to retrieve the resource
-     *
-     * The original High Fidelity used the Public, Content and MPAssets buckets. The intention is that the
-     * community-run versions of these will keep the original data and structure, and any new additions
-     * will be done to the Assets bucket instead. This should ease the transition and ensure a clean
-     * separation.
+    /**jsdoc
+     * <p>An external resource bucket.</p>
+     * <p>The original High Fidelity used "Public", "Content", and "MPAssets" Amazon S3 buckets. The intention is that the
+     * community-run versions of these will keep the original data and structure, and any new additions will be made to 
+     * Vircadia's "Assets" bucket. This should ease the transition from High Fidelity and ensure a clean separation.</p>
+     * @typedef {object} Script.ResourceBuckets
+     * @property {Script.ResourceBucket} Assets - Vircadia assets.
+     * @property {Script.ResourceBucket} HF_Public - Assets that used to be in High Fidelity's <code>hifi-public</code> Amazon 
+     *     S3 bucket.
+     * @property {Script.ResourceBucket} HF_Content - Assets that used to be in High Fidelity's <code>hifi-content</code> Amazon
+     *     S3 bucket.
+     * @property {Script.ResourceBucket} HF_Marketplace - Assets that used to be in the High Fidelity's <code>mpassets</code>
+     *     Amazon S3 bucket. (High Fidelity marketplace.)
+     */
+    /**jsdoc
+     * <p>An external resource bucket.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>HF_Public</td><td>Assets that used to be in High Fidelity's <code>hifi-public</code>
+     *       Amazon S3 bucket.</td></tr>
+     *     <tr><td><code>1</code></td><td>HF_Content</td><td>Assets that used to be in High Fidelity's <code>hifi-content</code>
+     *       Amazon S3 bucket.</td></tr>
+     *     <tr><td><code>2</code></td><td>HF_Marketplace</td><td>Assets that used to be in the High Fidelity's 
+     *       <code>mpassets</code> Amazon S3 bucket. (High Fidelity marketplace.)</td></tr>
+     *     <tr><td><code>3</code></td><td>Assets</td><td>Vircadia assets.</td></tr>
+     *   </tbody>
+     * </table>
+     * @typedef {number} Script.ResourceBucket
      */
     enum class Bucket {
-        /** Assets that used to be in the hifi-public S3 bucket */
         HF_Public,
-
-        /** Assets that used to be in the hifi-content S3 bucket */
         HF_Content,
-
-        /** Assets that used to be in the mpassets S3 bucket (hifi marketplace) */
         HF_Marketplace,
-
-        /** Vircadia assets */
-        Assets,
-        Public,
-        Content
+        Assets
     };
     Q_ENUM(Bucket)
 
@@ -155,9 +170,7 @@ private:
         { Bucket::HF_Public, QUrl(NetworkingConstants::HF_PUBLIC_CDN_URL) },
         { Bucket::HF_Content, QUrl(NetworkingConstants::HF_CONTENT_CDN_URL) },
         { Bucket::HF_Marketplace, QUrl(NetworkingConstants::HF_MPASSETS_CDN_URL) },
-        { Bucket::Assets, QUrl(NetworkingConstants::VIRCADIA_CONTENT_CDN_URL) },
-        { Bucket::Public, QUrl(NetworkingConstants::VIRCADIA_CONTENT_CDN_URL) },
-        { Bucket::Content, QUrl(NetworkingConstants::VIRCADIA_CONTENT_CDN_URL) }
+        { Bucket::Assets, QUrl(NetworkingConstants::VIRCADIA_CONTENT_CDN_URL) }
     };
 };
 

libraries/script-engine/src/ScriptEngine.h

@@ -121,6 +121,7 @@ public:
  *       <li><code>"agent"</code>: An assignment client script.</li>
  *     </ul>
  *     <em>Read-only.</em>
+ * @property {Script.ResourceBuckets} ExternalPaths - External resource buckets.
  */
 class ScriptEngine : public BaseScriptEngine, public EntitiesScriptEngineProvider {
     Q_OBJECT
@@ -235,12 +236,12 @@ public:
 
     /**jsdoc
      * @function Script.registerEnum
-     * @param {string} enumName - Name.
-     * @param {object} newEnum - Enumeration to be added
-     * @warning This function must be called after a registerGlobalObject that creates the namespace this enum is located in,
-     * or the globalObject won't function. Eg, if you have a Foo object and a Foo.FooType enum, Foo must be registered first.
+     * @param {string} name - Name.
+     * @param {object} enum - Enum.
      * @deprecated This function is deprecated and will be removed.
      */
+    // WARNING: This function must be called after a registerGlobalObject that creates the namespace this enum is located in, or\
+    // the globalObject won't function. E.g., if you have a Foo object and a Foo.FooType enum, Foo must be registered first.
     /// registers a global enum
     Q_INVOKABLE void registerEnum(const QString& enumName, QMetaEnum newEnum);
 
@@ -684,6 +685,16 @@ public:
 
     void setScriptEngines(QSharedPointer<ScriptEngines>& scriptEngines) { _scriptEngines = scriptEngines; }
 
+    /**jsdoc
+     * Gets the URL for an asset in an external resource bucket. (The location where the bucket is hosted may change over time
+     * but this method will return the asset's current URL.)
+     * @function Script.getExternalPath
+     * @param {Script.ResourceBucket} bucket - The external resource bucket that the asset is in.
+     * @param {string} relativePath - The path within the external resource bucket where the asset is located.
+     * @Returns {string} The URL of an external asset.
+     * @example <caption>Report the root directory where the Vircadia assets are located.</caption>
+     * print("Script.getExternalPath(Script.ExternalPaths.Assets, ""));
+     */
     Q_INVOKABLE QString getExternalPath(ExternalResource::Bucket bucket, const QString& relativePath);
 
 public slots: