From ba7242f4dc6ef7acd7d38194ad58d199b9b4f0b6 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 23 Sep 2020 17:23:40 +1200 Subject: [PATCH] Script.getExternalPath() and related JSDoc --- libraries/networking/src/ExternalResource.h | 53 +++++++++++++-------- libraries/script-engine/src/ScriptEngine.h | 19 ++++++-- 2 files changed, 48 insertions(+), 24 deletions(-) diff --git a/libraries/networking/src/ExternalResource.h b/libraries/networking/src/ExternalResource.h index c2a08c02a5..e80e1c8099 100644 --- a/libraries/networking/src/ExternalResource.h +++ b/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 + *

An external resource bucket.

+ *

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.

+ * @typedef {object} Script.ResourceBuckets + * @property {Script.ResourceBucket} Assets - Vircadia assets. + * @property {Script.ResourceBucket} HF_Public - Assets that used to be in High Fidelity's hifi-public Amazon + * S3 bucket. + * @property {Script.ResourceBucket} HF_Content - Assets that used to be in High Fidelity's hifi-content Amazon + * S3 bucket. + * @property {Script.ResourceBucket} HF_Marketplace - Assets that used to be in the High Fidelity's mpassets + * Amazon S3 bucket. (High Fidelity marketplace.) + */ + /**jsdoc + *

An external resource bucket.

+ * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0HF_PublicAssets that used to be in High Fidelity's hifi-public + * Amazon S3 bucket.
1HF_ContentAssets that used to be in High Fidelity's hifi-content + * Amazon S3 bucket.
2HF_MarketplaceAssets that used to be in the High Fidelity's + * mpassets Amazon S3 bucket. (High Fidelity marketplace.)
3AssetsVircadia assets.
+ * @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) } }; }; diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index abb232a0f5..07b37b992b 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -121,6 +121,7 @@ public: *
  • "agent": An assignment client script.
    • * * Read-only. + * @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; } + /**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 Report the root directory where the Vircadia assets are located. + * print("Script.getExternalPath(Script.ExternalPaths.Assets, "")); + */ Q_INVOKABLE QString getExternalPath(ExternalResource::Bucket bucket, const QString& relativePath); public slots: