History

Tidying and polishing Assets JSDoc

David Rowe committed 7 years ago

Commit 9457aed1 parent 8820d1d4 files · +202 −210Browse files

Showing the changes to libraries/script-engine/src/AssetScriptingInterface.cpp (1 of 4 files). Show all

Unified · Split

libraries/script-engine/src/AssetScriptingInterface.cpp+110−4
@@ -81,6 +81,11 @@ void AssetScriptingInterface::setMapping(QString path, QString hash, QScriptValu · 80 unmodified lines
81 setMappingRequest->start();81 setMappingRequest->start();
82}82}
83 83
84/**jsdoc
85 * The success or failure of an {@link Assets.downloadData} call.
86 * @typedef {object} Assets.DownloadDataError
87 * @property {string} errorMessage - <code>""</code> if the download was successful, otherwise a description of the error.
88 */
84void AssetScriptingInterface::downloadData(QString urlString, QScriptValue callback) {89void AssetScriptingInterface::downloadData(QString urlString, QScriptValue callback) {
85 // FIXME: historically this API method failed silently when given a non-atp prefixed90 // FIXME: historically this API method failed silently when given a non-atp prefixed
86 // urlString (or if the AssetRequest failed).91 // urlString (or if the AssetRequest failed).
@@ -215,6 +220,32 @@ void AssetScriptingInterface::deleteAsset(QScriptValue options, QScriptValue sco · 128 unmodified lines
215 jsVerify(false, "TODO: deleteAsset API");220 jsVerify(false, "TODO: deleteAsset API");
216}221}
217 222
223/**jsdoc
224 * Source and download options for {@link Assets.getAsset}.
225 * @typedef {object} Assets.GetOptions
226 * @property {boolean} [decompress=false] - <code>true</code> to gunzip decompress the downloaded data. Synonym:
227 * <code>compressed</code>.
228 * @property {Assets.ResponseType} [responseType="text"] - The desired result type.
229 * @property {string} url - The mapped path or hash to download. May have a leading <code>"atp:"</code>.
230 */
231/**jsdoc
232 * Result value returned by {@link Assets.getAsset}.
233 * @typedef {object} Assets.GetResult
234 * @property {number} [byteLength] - The number of bytes in the downloaded content in <code>response</code>.
235 * @property {boolean} cached - <code>true</code> if the item was retrieved from the cache, <code>false</code> if it was
236 * downloaded.
237 * @property {string} [contentType] - The automatically detected MIME type of the content.
238 * @property {boolean} [decompressed] - <code>true</code> if the content was decompressed, <code>false</code> if it wasn't.
239 * @property {string} [hash] - The hash for the downloaded asset.
240 * @property {string} [hashURL] - The ATP URL of the hash file.
241 * @property {string} [path] - The path for the asset, if a path was requested. Otherwise, <code>undefined</code>.
242 * @property {string|object|ArrayBuffer} [response] - The downloaded content.
243 * @property {Assets.ResponseType} [responseType] - The type of the downloaded content in <code>response</code>.
244 * @property {string} [url] - The URL of the asset requested: the path with leading <code>"atp:"</code> if a path was
245 * requested, otherwise the requested URL.
246 * @property {boolean} [wasRedirected] - <code>true</code> if the downloaded data is the baked version of the asset,
247 * <code>false</code> if it isn't baked.
248 */
218void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {249void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
219 JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter");250 JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter");
220 251
@@ -262,6 +293,22 @@ void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, · 41 unmodified lines
262 }293 }
263}294}
264 295
296/**jsdoc
297 * Source options for {@link Assets.resolveAsset}.
298 * @typedef {object} Assets.ResolveOptions
299 * @property {string} url - The hash or path to resolve. May have a leading <code>"atp:"</code>.
300 */
301/**jsdoc
302 * Result value returned by {@link Assets.resolveAsset}.
303 * <p>Note: If resolving a hash, a file of that hash need not be present on the asset server for the hash to resolve.</p>
304 * @typedef {object} Assets.ResolveResult
305 * @property {string} [hash] - The hash of the asset.
306 * @property {string} [hashURL] - The url of the asset's hash file, with leading <code>atp:</code>.
307 * @property {string} [path] - The path to the asset.
308 * @property {string} [url] - The URL of the asset.
309 * @property {boolean} [wasRedirected] - <code>true</code> if the resolved data is for the baked version of the asset,
310 * <code>false</code> if it isn't.
311 */
265void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {312void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
266 const QString& URL{ "url" };313 const QString& URL{ "url" };
267 314
@@ -274,6 +321,21 @@ void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue sc · 6 unmodified lines
274 jsPromiseReady(getAssetInfo(asset), scope, callback);321 jsPromiseReady(getAssetInfo(asset), scope, callback);
275}322}
276 323
324/**jsdoc
325 * Content and decompression options for {@link Assets.decompressData}.
326 * @typedef {object} Assets.DecompressOptions
327 * @property {ArrayBuffer} data - The data to decompress.
328 * @property {Assets.ResponseType} [responseType=text] - The type of decompressed data to return.
329 */
330/**jsdoc
331 * Result value returned by {@link Assets.decompressData}.
332 * @typedef {object} Assets.DecompressResult
333 * @property {number} [byteLength] - The number of bytes in the decompressed data.
334 * @property {string} [contentType] - The MIME type of the decompressed data.
335 * @property {boolean} [decompressed] - <code>true</code> if the data is decompressed.
336 * @property {string|object|ArrayBuffer} [response] - The decompressed data.
337 * @property {Assets.ResponseType} [responseType] - The type of the decompressed data in <code>response</code>.
338 */
277void AssetScriptingInterface::decompressData(QScriptValue options, QScriptValue scope, QScriptValue callback) {339void AssetScriptingInterface::decompressData(QScriptValue options, QScriptValue scope, QScriptValue callback) {
278 auto data = options.property("data");340 auto data = options.property("data");
279 QByteArray dataByteArray = qscriptvalue_cast<QByteArray>(data);341 QByteArray dataByteArray = qscriptvalue_cast<QByteArray>(data);
@@ -298,6 +360,23 @@ namespace { · 18 unmodified lines
298 const int32_t DEFAULT_GZIP_COMPRESSION_LEVEL = -1;360 const int32_t DEFAULT_GZIP_COMPRESSION_LEVEL = -1;
299 const int32_t MAX_GZIP_COMPRESSION_LEVEL = 9;361 const int32_t MAX_GZIP_COMPRESSION_LEVEL = 9;
300}362}
363
364/**jsdoc
365 * Content and compression options for {@link Assets.compressData}.
366 * @typedef {object} Assets.CompressOptions
367 * @property {string|ArrayBuffer} data - The data to compress.
368 * @property {number} level - The compression level, range <code>-1</code> &ndash; <code>9</code>. <code>-1</code> means
369 * use the default gzip compression level, <code>0</code> means no compression, and <code>9</code> means maximum
370 * compression.
371 */
372/**jsdoc
373 * Result value returned by {@link Assets.compressData}.
374 * @typedef {object} Assets.CompressResult
375 * @property {number} [byteLength] - The number of bytes in the compressed data.
376 * @property {boolean} [compressed] - <code>true</code> if the data is compressed.
377 * @property {string} [contentType] - The MIME type of the compressed data, i.e., <code>"application/gzip"</code>.
378 * @property {ArrayBuffer} [data] - The compressed data.
379 */
301void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue scope, QScriptValue callback) {380void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue scope, QScriptValue callback) {
302 auto data = options.property("data").isValid() ? options.property("data") : options;381 auto data = options.property("data").isValid() ? options.property("data") : options;
303 QByteArray dataByteArray = data.isString() ? data.toString().toUtf8() : qscriptvalue_cast<QByteArray>(data);382 QByteArray dataByteArray = data.isString() ? data.toString().toUtf8() : qscriptvalue_cast<QByteArray>(data);
@@ -306,6 +385,27 @@ void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue sc · 2 unmodified lines
306 jsPromiseReady(compressBytes(dataByteArray, level), scope, callback);385 jsPromiseReady(compressBytes(dataByteArray, level), scope, callback);
307}386}
308 387
388/**jsdoc
389 * Content and upload options for {@link Assets.putAsset}.
390 * @typedef {object} Assets.PutOptions
391 * @property {boolean} [compress=false] - <code>true</code> to gzip compress the content for upload and storage,
392 * <code>false</code> to upload and store the data without gzip compression. Synonym: <code>compressed</code>.
393 * @property {string|ArrayBuffer} data - The content to upload.
394 * @property {string} [path] - A user-friendly path for the file in the asset server. May have a leading
395 * <code>"atp:"</code>. IF not specified, no path-to-hash mapping is set.
396 * <p>Note: The asset server destroys any unmapped SHA256-named file at server restart. Either set the mapping path
397 * with this property or use {@link Assets.setMapping} to set a path-to-hash mapping for the uploaded file.</p>
398 */
399/**jsdoc
400 * Result value returned by {@link Assets.putAsset}.
401 * @typedef {object} Assets.PutResult
402 * @property {number} [byteLength] - The number of bytes in the hash file stored on the asset server.
403 * @property {boolean} [compressed] - <code>true</code> if the content stored is gzip compressed.
404 * @property {string} [contentType] - <code>"application/gzip"</code> if the content stored is gzip compressed.
405 * @property {string} [hash] - The SHA256 hash of the content.
406 * @property {string} [url] - The <code>atp:</code> URL of the content: using the path if specified, otherwise the hash.
407 * @property {string} [path] - The uploaded content's mapped path, if specified.
408 */
309void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {409void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
310 auto compress = options.property("compress").toBool() || options.property("compressed").toBool();410 auto compress = options.property("compress").toBool() || options.property("compressed").toBool();
311 auto data = options.isObject() ? options.property("data") : options;411 auto data = options.isObject() ? options.property("data") : options;
@@ -356,6 +456,12 @@ void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, · 44 unmodified lines
356 }456 }
357}457}
358 458
459/**jsdoc
460 * Source for {@link Assets.queryCacheMeta}.
461 * @typedef {object} Assets.QueryCacheMetaOptions
462 * @property {string} url - The URL of the cached asset to get information on. Must start with <code>"atp:"</code> or
463 * <code>"cache:"</code>.
464 */
359void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue scope, QScriptValue callback) {465void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue scope, QScriptValue callback) {
360 QString url = options.isString() ? options.toString() : options.property("url").toString();466 QString url = options.isString() ? options.toString() : options.property("url").toString();
361 JS_VERIFY(QUrl(url).isValid(), QString("Invalid URL '%1'").arg(url));467 JS_VERIFY(QUrl(url).isValid(), QString("Invalid URL '%1'").arg(url));
@@ -365,11 +471,11 @@ void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue · 3 unmodified lines
365/**jsdoc471/**jsdoc
366 * Source and retrieval options for {@link Assets.loadFromCache}.472 * Source and retrieval options for {@link Assets.loadFromCache}.
367 * @typedef {object} Assets.LoadFromCacheOptions473 * @typedef {object} Assets.LoadFromCacheOptions
368 * @property {string} url - The URL of the asset to load from cache. Must start with <code>"atp:"</code> or 474 * @property {boolean} [decompress=false] - <code>true</code> to gunzip decompress the cached data. Synonym:
369 * <code>"cache:"</code>.
370 * @property {Assets.ResponseType} [responseType=text] - The desired result type.
371 * @property {boolean} [decompress=false] - <code>true</code> to gunzip decompress the cached data. Synonym:
372 * <code>compressed</code>.475 * <code>compressed</code>.
476 * @property {Assets.ResponseType} [responseType=text] - The desired result type.
477 * @property {string} url - The URL of the asset to load from cache. Must start with <code>"atp:"</code> or
478 * <code>"cache:"</code>.
373 */479 */
374void AssetScriptingInterface::loadFromCache(QScriptValue options, QScriptValue scope, QScriptValue callback) {480void AssetScriptingInterface::loadFromCache(QScriptValue options, QScriptValue scope, QScriptValue callback) {
375 QString url, responseType;481 QString url, responseType;