update description

src/scriptlets/trusted-set-constant.js

@@ -25,83 +25,67 @@ import {
 
 /* eslint-disable max-len */
 /**
- * @scriptlet set-constant
+ * @scriptlet trusted-set-constant
  *
  * @description
- * Creates a constant property and assigns it one of the values from the predefined list.
+ * Creates a constant property and assigns it a specified value.
  *
  * > Actually, it's not a constant. Please note, that it can be rewritten with a value of a different type.
  *
  * > If empty object is present in chain it will be trapped until chain leftovers appear.
  *
- * Related UBO scriptlet:
- * https://github.com/gorhill/uBlock/wiki/Resources-Library#set-constantjs-
- *
- * Related ABP snippet:
- * https://github.com/adblockplus/adblockpluscore/blob/adblockpluschrome-3.9.4/lib/content/snippets.js#L1361
+ * > Use [set-constant](./about-scriptlets.md#set-constant) to set predefined values and functions
  *
  * **Syntax**
  * ```
- * example.org#%#//scriptlet('set-constant', property, value[, stack])
+ * example.org#%#//scriptlet('trusted-set-constant', property, value[, inferType[, stack]])
  * ```
  *
  * - `property` - required, path to a property (joined with `.` if needed). The property must be attached to `window`.
- * - `value` - required. Possible values:
- *     - positive decimal integer `<= 32767`
- *     - one of the predefined constants:
- *         - `undefined`
- *         - `false`
- *         - `true`
- *         - `null`
- *         - `emptyObj` - empty object
- *         - `emptyArr` - empty array
- *         - `noopFunc` - function with empty body
- *         - `noopCallbackFunc` - function returning noopFunc
- *         - `trueFunc` - function returning true
- *         - `falseFunc` - function returning false
- *         - `throwFunc` - function throwing an error
- *         - `noopPromiseResolve` - function returning Promise object that is resolved with an empty response
- *         - `noopPromiseReject` - function returning Promise.reject()
- *         - `''` - empty string
- *         - `-1` - number value `-1`
- *         - `yes`
- *         - `no`
+ * - `value` - required, an arbitrary value to be set.
+ * - `inferType`  - optional, boolean, to convert specified `value` argument to an inferred type, e.g set `NaN` value instead of `'NaN'` string;
+ * defaults to no conversion, effectively making `string` the default value type.
  * - `stack` - optional, string or regular expression that must match the current function call stack trace;
  * if regular expression is invalid it will be skipped
  *
  * **Examples**
+ * 1. Set property values of different types
  * ```
- * ! Any access to `window.first` will return `false`
- * example.org#%#//scriptlet('set-constant', 'first', 'false')
+ * ! Set string value
+ * example.org#%#//scriptlet('trusted-set-constant', 'click_r', '0')
  *
- * ✔ window.first === false
- * ```
+ * ✔ window.click_r === '0'
+ * ✔ typeof window.click_r === 'string'
  *
- * ```
- * ! Any call to `window.second()` will return `true`
- * example.org#%#//scriptlet('set-constant', 'second', 'trueFunc')
+ * ! Set number value
+ * example.org#%#//scriptlet('trusted-set-constant', 'click_r', '0', 'true')
+ *
+ * ✔ window.click_r === 0
+ * ✔ typeof window.click_r === 'number'
  *
- * ✔ window.second() === true
- * ✔ window.second.toString() === "function trueFunc() {return true;}"
+ * ! Set array or object as property value, argument should be a JSON string
+ * example.org#%#//scriptlet('trusted-set-constant', 'click_r', '[1,"string"]', 'true')
+ * example.org#%#//scriptlet('trusted-set-constant', 'click_r', ''{"aaa":123,"bbb":{"ccc":"string"}}'', 'true')
  * ```
  *
+ * 2. Use script stack matching to set value
  * ```
- * ! Any call to `document.third()` will return `true` if the method is related to `checking.js`
- * example.org#%#//scriptlet('set-constant', 'document.third', 'trueFunc', 'checking.js')
+ * ! Any call to `document.first` will return `'1'` if the method is related to `checking.js`
+ * example.org#%#//scriptlet('trusted-set-constant', 'document.first', '1', '', 'checking.js')
  *
- * ✔ document.third() === true  // if the condition described above is met
+ * ✔ document.first === '1'  // if the condition described above is met
  * ```
  */
 /* eslint-enable max-len */
-export function trustedSetConstant(source, property, value, shouldInfer, stack) {
+export function trustedSetConstant(source, property, value, inferType, stack) {
     if (!property
         || !matchStackTrace(stack, new Error().stack)) {
         return;
     }
 
     let constantValue;
     try {
-        constantValue = shouldInfer === 'infer' ? inferValue(value) : value;
+        constantValue = inferType === 'true' ? inferValue(value) : value;
     } catch (e) {
         logMessage(source, e);
         return;