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
8181 setMappingRequest->start();
8282 }
8383
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+ */
8489 void AssetScriptingInterface::downloadData(QString urlString, QScriptValue callback) {
8590 // FIXME: historically this API method failed silently when given a non-atp prefixed
8691 // urlString (or if the AssetRequest failed).
@@ -215,6 +220,32 @@ void AssetScriptingInterface::deleteAsset(QScriptValue options, QScriptValue sco · 128 unmodified lines
215220 jsVerify(false, "TODO: deleteAsset API");
216221 }
217222
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+ */
218249 void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
219250 JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter");
220251
@@ -262,6 +293,22 @@ void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, · 41 unmodified lines
262293 }
263294 }
264295
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+ */
265312 void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
266313 const QString& URL{ "url" };
267314
@@ -274,6 +321,21 @@ void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue sc · 6 unmodified lines
274321 jsPromiseReady(getAssetInfo(asset), scope, callback);
275322 }
276323
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+ */
277339 void AssetScriptingInterface::decompressData(QScriptValue options, QScriptValue scope, QScriptValue callback) {
278340 auto data = options.property("data");
279341 QByteArray dataByteArray = qscriptvalue_cast<QByteArray>(data);
@@ -298,6 +360,23 @@ namespace { · 18 unmodified lines
298360 const int32_t DEFAULT_GZIP_COMPRESSION_LEVEL = -1;
299361 const int32_t MAX_GZIP_COMPRESSION_LEVEL = 9;
300362 }
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+ */
301380 void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue scope, QScriptValue callback) {
302381 auto data = options.property("data").isValid() ? options.property("data") : options;
303382 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
306385 jsPromiseReady(compressBytes(dataByteArray, level), scope, callback);
307386 }
308387
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+ */
309409 void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
310410 auto compress = options.property("compress").toBool() || options.property("compressed").toBool();
311411 auto data = options.isObject() ? options.property("data") : options;
@@ -356,6 +456,12 @@ void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, · 44 unmodified lines
356456 }
357457 }
358458
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+ */
359465 void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue scope, QScriptValue callback) {
360466 QString url = options.isString() ? options.toString() : options.property("url").toString();
361467 JS_VERIFY(QUrl(url).isValid(), QString("Invalid URL '%1'").arg(url));
@@ -365,11 +471,11 @@ void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue · 3 unmodified lines
365471 /**jsdoc
366472 * Source and retrieval options for {@link Assets.loadFromCache}.
367473 * @typedef {object} Assets.LoadFromCacheOptions
368− * @property {string} url - The URL of the asset to load from cache. Must start with <code>"atp:"</code> or
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:
474+ * @property {boolean} [decompress=false] - <code>true</code> to gunzip decompress the cached data. Synonym:
372475 * <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>.
373479 */
374480 void AssetScriptingInterface::loadFromCache(QScriptValue options, QScriptValue scope, QScriptValue callback) {
375481 QString url, responseType;