@lumjs/core 1.0.0-beta.4 → 1.0.0-beta.6

package/lib/obj/clone.js

@@ -19,6 +19,7 @@ const copyProps = require('./copyprops');
  * | `CLONE.ENTIRE` | ✓ | × | ✓ | |
  * | `CLONE.JSON` | × | × | ✓ | Uses JSON, so no `function` or `symbol` support. |
  * 
+ * @alias module:@lumjs/core/obj.CLONE
  */
  const CLONE = Enum(['DEF','FULL','ALL','DEEP','ENTIRE','JSON']);
 
@@ -43,25 +44,26 @@ const copyProps = require('./copyprops');
   * 
   *   Note: The `CLONE` enum is also aliased as `clone.MODE` as an alternative.
   *
-  * @param {boolean} [opts.addClone=false] - Call {@link Lum._.addClone} on the cloned object.
+  * @param {boolean} [opts.addClone=false] - Call `addClone()` on the cloned object.
   *
   *   The options sent to this function will be used as the defaults in
-  *   the clone() method added to the object.
+  *   the `clone()` method added to the object.
   *
-  * @param {boolean} [opts.addLock=false] - Call {@link Lum._.addLock} on the cloned object.
+  * @param {boolean} [opts.addLock=false] - Call `addLock()` on the cloned object.
   *
-  *   No further options for this, just add a lock() method to the clone.
+  *   No further options for this, just add a `lock()` method to the clone.
   *
-  * @param {?object} [opts.copy] Call {@link Lum._.copy} on the cloned object.
+  * @param {?object} [opts.copy] Call `copyProps()` on the cloned object.
   *
   *   Will pass the original `obj` as the source to copy from.
   *   Will pass `opts.copy` as the options.
   *
   * @return {object} - The clone of the object.
+  * @alias module:@lumjs/core/obj.clone
   */
 function clone(obj, opts={}) 
 {
-  //console.debug("Lum~clone()", obj, opts);
+  //console.debug("clone()", obj, opts);
 
   if (!isComplex(obj))
   { // Doesn't need cloning.
@@ -156,7 +158,7 @@ exports.clone = clone;
   *
   * ```{mode: CLONE.DEF, addClone: true, addLock: false}```
   *
-  * @method Lum._.addClone
+  * @alias module:@lumjs/core/obj.addClone
   */
 function addClone(obj, defOpts=null)
 {
@@ -185,14 +187,14 @@ exports.addClone = addClone;
   * If the object is extensible, it's returned as is.
   *
   * If not, if the object has a `clone()` method it will be used.
-  * Otherwise use the {@link Lum._.clone} method.
+  * Otherwise use our `clone()` function.
   *
   * @param {object} obj - The object to clone if needed.
   * @param {object} [opts] - Options to pass to `clone()` method.
   *
   * @return {object} - Either the original object, or an extensible clone.
   *
-  * @method Lum._.cloneIfLocked
+  * @alias module:@lumjs/core/obj.cloneIfLocked
   */
 function cloneIfLocked(obj, opts)
 {

package/lib/obj/copyall.js

@@ -3,6 +3,8 @@
  *
  * It does no type checking, and has no qualms about overwriting properties.
  * You probably want something like `copyProps` instead.
+ * 
+ * @alias module:@lumjs/core/obj.copyAll
  */
 function copyAll(target, ...sources)
 {
@@ -13,6 +15,7 @@ function copyAll(target, ...sources)
       target[name] = source[name];
     }
   }
+  return target;
 }
 
 module.exports = copyAll;

package/lib/obj/copyprops.js

@@ -23,6 +23,7 @@ const {B,isObj,isComplex,isArray,def: defProp} = require('../types');
  *   if that property can be overwritten or not.
  *
  * @returns {object} The `target` object.
+ * @alias module:@lumjs/core/obj.copyProps
  */
 function copyProps(source, target, propOpts)
 {

package/lib/obj/index.js

@@ -1,7 +1,7 @@
-// Object helper utilities.
-// We *could* use `copyAll` to simply merge everything in here automatically.
-// But I'm going to be more explicit and import everything I want separately.
-// I may change my mind on that in the future, who knows.
+/**
+ * Object helpers sub-module.
+ * @module @lumjs/core/obj
+ */
 
 const copyAll = require('./copyall');
 const copyProps = require('./copyprops');

package/lib/obj/lock.js

@@ -5,8 +5,8 @@ const {B, isObj, def} = require('../types');
  * Lock an object using Object.freeze()
  *
  * @param {object} obj - The object we want to lock.
- * @param {boolean} [clonable=true] Pass to {@link Lum._.addClone} first?
- * @param {object} [cloneOpts=null] Options for addClone.
+ * @param {boolean} [clonable=true] Pass to `addClone()` first?
+ * @param {object} [cloneOpts=null] Options for `addClone()`.
  * @param {boolean} [useSeal=false] Use Object.seal() instead of freeze.
  *
  * If cloneOpts is `null` then we will use the following:
@@ -14,8 +14,7 @@ const {B, isObj, def} = require('../types');
  * ```{mode: CLONE.DEF, addClone: true, addLock: true}```
  *
  * @return {object} The locked object.
- *
- * @method Lum._.lock
+ * @alias module:@lumjs/core/obj.lock
  */
  function lock(obj, clonable=true, cloneOpts=null, useSeal=false)
  {
@@ -37,12 +36,17 @@ const {B, isObj, def} = require('../types');
  /**
   * Add a lock() method to an object.
   *
-  * Adds a wrapper version of {@link Lum._.lock} to the object as a method.
-  *
-  * @param {object} obj - The object we're adding lock() to.
-  * @param {object} opts - Options (TODO: document this).
+  * Adds a wrapper version of `lock()` to the object as a method.
   *
-  * @method Lum._.addLock
+  * @param {object} obj - The object we're adding `lock()` to.
+  * @param {object} [opts] - Options and defaults. 
+  *   In addition to options specific to this function, any options
+  *   supported by `addClone()` may be specified here as well.
+  * @param {object} [opts.lockDesc] Descriptor rules the `lock()` method.
+  * @param {boolean} [opts.addClone=true] Default for `clonable` parameter.
+  * @param {object} [opts.useSeal=false] Default for `useSeal` parameter.
+  * @returns {object} `obj`
+  * @alias module:@lumjs/core/obj.addLock
   */
  function addLock(obj, opts)
  {

package/lib/obj/merge.js

@@ -20,6 +20,7 @@ const {B, isObj} = require('../types');
  *   as the `opts` argument directly will set this option.
  *
  * @returns {object} The `target` object.
+ * @alias module:@lumjs/core/obj.mergeNested
  */
  function mergeNested(source, target, opts={})
  {
@@ -64,6 +65,7 @@ const {B, isObj} = require('../types');
   * @param {object} [opts2=opts1] Options for the second merge operation.
   *   If this is not specified, `opts2` will be the same as `opts1`.
   *
+  * @alias module:@lumjs/core/obj.syncNested
   */
  function syncNested(obj1, obj2, opts1={}, opts2=opts1)
  {

package/lib/obj/ns.js

@@ -5,13 +5,14 @@ const
 } = require('../types');
 
 /**
- * Internal: need a String or Array
+ * Need a String or Array
+ * @alias module:@lumjs/core/obj.SOA
  */
 function SOA(name, err=true)
 {
   const msg = (typeof name === S) 
-    ? name + ' ' + this.message 
-    : this.message;
+    ? name + ' ' + SOA.message 
+    : SOA.message;
   return err ? (new TypeError(msg)) : msg;
 }
 SOA.message = "must be a string or non-empty array";
@@ -19,6 +20,17 @@ def(SOA, 'toString', function() { return this.message; });
 
 exports.SOA = SOA;
 
+/**
+ * Get a namespace path string.
+ * 
+ * If it's already a string, return it as is.
+ * If it's an array of strings, join the elements with a `.` character.
+ * 
+ * @param {(string|string[])} ns - A dotted string, or array of paths.
+ * @param {*} name - Name to use in the SOA error 
+ * @returns {string} 
+ * @alias module:@lumjs/core/obj.nsString
+ */
 function nsString(ns, name='Namespace')
 {
   if (nonEmptyArray(ns))
@@ -34,6 +46,17 @@ function nsString(ns, name='Namespace')
 
 exports.nsString = nsString;
 
+/**
+ * Get a namespace path array.
+ * 
+ * If it's already an array, return it as is.
+ * If it's a string, split it into an array, with the `.` delimiter.
+ * 
+ * @param {(string|string[])} ns - A dotted string, or array of paths.
+ * @param {*} name - Name to use in the SOA error 
+ * @returns {string[]} 
+ * @alias module:@lumjs/core/obj.nsArray
+ */
 function nsArray(ns, name='Namespace')
 {
   if (typeof ns === S)
@@ -57,6 +80,7 @@ exports.nsArray = nsArray;
  *   Generally a string of dot (`.`) separated nested property names.
  * @param {object} [opts] TBD.
  * @return {*} The property if found, or `opts.default` if not.
+ * @alias module:@lumjs/core/obj.getObjectPath
  */
 function getObjectPath(obj, proppath, opts={})
 {
@@ -97,6 +121,7 @@ exports.getObjectPath = getObjectPath;
  * @param {object} [opts] TBD.
  * @return {*} Generally the last object in the nested path.
  *   However the output may vary depending on the options.
+ * @alias module:@lumjs/core/obj.setObjectPath
  */
 function setObjectPath(obj, proppath, opts={})
 {
@@ -169,9 +194,15 @@ exports.setObjectPath = setObjectPath;
 
 /**
  * Get a global namespace path if it exists.
+ *
+ * This literally just calls `getObjectPath()` on the `root` object.
  * 
- * - TODO: document this.
- * - TODO: rewrite `ns.get` to use this behind the scenes.
+ * @param {(string|Array)} proppath - Property path we're looking for.
+ *   Generally a string of dot (`.`) separated nested property names.
+ * @param {object} [opts] See `getObjectPath()` for details.
+ * @return {*} The property if found, or `opts.default` if not.
+ * @alias module:@lumjs/core/obj.getNamespace
+ * @see module:@lumjs/core/obj.getObjectPath
  */
 function getNamespace(namespaces, opts={})
 {
@@ -183,12 +214,18 @@ exports.getNamespace = getNamespace;
 /**
  * Create a global namespace path if it does not exist.
  * 
- * - TODO: document this.
- * - TODO: rewrite `ns.add` to use this behind the scenes.
+ * This literally just calls `setObjectPath()` on the `root` object.
+ * 
+ * @param {(string|Array)} proppath - Property path to create.
+ * @param {object} [opts] See `setObjectPath()` for details.
+ * @return {*} Generally the last object in the nested path.
+ *   However the output may vary depending on the options.
+ * @alias module:@lumjs/core/obj.setNamespace
+ * @see module:@lumjs/core/obj.setObjectPath
  */
 function setNamespace(namespaces, opts={})
 {
   return setObjectPath(root, namespaces, opts);
 }
 
-exports.setNamespace = setNamespace;
+exports.setNamespace = setNamespace;

package/lib/objectid.js

@@ -4,9 +4,8 @@ const {notNil,def,isNil} = require('./types');
 /**
  * Generate a large random number.
  * 
- * Takes advantage of 
- * 
  * @returns {number}
+ * @alias module:@lumjs/core.randomNumber
  */
 function randomNumber()
 {
@@ -18,6 +17,7 @@ exports.randomNumber = randomNumber;
 /**
  * A class for creating unique identifier objects.
  * Generally only used by my own inernal libraries, thus the name.
+ * @alias module:@lumjs/core.InternalObjectId
  */
 class InternalObjectId
 {
@@ -34,7 +34,6 @@ class InternalObjectId
    * @param {boolean} [opts.useInstance=true] Store object or id value?
    *   If this is `true` (now the default), we store the instance itself.
    *   If this is `false` (the old default), we store just the `id` value.
-   * 
    */
   constructor(opts={})
   {

package/lib/observable.js

@@ -1,11 +1,8 @@
-// This library was original based on the observable library from riot.js,
-// but has been refactored and expanded a lot since then.
 
-const types = require('./types');
-const {B,F,S,def,isObj,isComplex} = types;
+const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');;
 
 /**
- * Make an object support the observable API.
+ * Make an object support the *Observable* API.
  *
  * Adds `on()`, `off()`, `one()`, and `trigger()` methods.
  * 
@@ -39,6 +36,8 @@ const {B,F,S,def,isObj,isComplex} = types;
  *   In any other case it defaults to `null`.
  *
  * @returns {object} el
+ * 
+ * @exports module:@lumjs/core/observable
  */
 function observable (el={}, opts={}) 
 {
@@ -274,9 +273,10 @@ function observable (el={}, opts={})
 module.exports = observable;
 
 /**
- * See if an object appears to be observable.
+ * See if a value implements the *Observable* interface.
  * 
- * @param {object} obj 
+ * @function module:@lumjs/core/observable.is
+ * @param {*} obj - The expected object/function to test.
  * @returns {boolean}
  */
 function isObservable(obj)
@@ -289,5 +289,19 @@ function isObservable(obj)
 // Add an 'is()' method to `observable` itself.
 def(observable, 'is', isObservable);
 
-// And make it available as `types.doesObservable`
-types.doesObservable = isObservable;
+/**
+ * Does a value implement the Observable interface?
+ * @name module:@lumjs/core/types.doesObservable
+ * @function
+ * @param {*} v - The expected object/function to test.
+ * @returns {boolean}
+ * @see module:@lumjs/core/observable.is
+ */
+
+/**
+ * Extension type for the {@link module:@lumjs/core/observable} interface.
+ * @memberof module:@lumjs/core/types.TYPES
+ * @member {string} OBSERV - Implements the *Observable* interface.
+ */
+
+TYPES.add('OBSERV', 'observable', isObservable, 'doesObservable');

package/lib/opt.js

@@ -1,4 +1,7 @@
-// Simple option handling.
+/**
+ * Functions for working with options and default values.
+ * @module @lumjs/core/opt
+ */
 
 const {U,needObj,needType} = require('./types');
 
@@ -16,6 +19,7 @@ const {U,needObj,needType} = require('./types');
  *                                    be used as `this` for the function.
  *
  * @return {*} Either the specified `opt` value or the default value.
+ * @alias module:@lumjs/core/opt.val
  */
 function val(opt, defvalue, allowNull=false, isLazy=false, lazyThis=null)
 {
@@ -49,6 +53,7 @@ exports.val = val;
  * @param {object} [lazyThis=opts]  Same as `val()`.
  *
  * @return {*} Either the property value, or the default value.
+ * module:@lumjs/core/opt.get
  */
 function get(obj, optname, defvalue, allowNull=true, isLazy=false, lazyThis=obj)
 {

package/lib/strings.js

@@ -1,4 +1,7 @@
-// String methods.
+/**
+ * String and locale related functions.
+ * @module @lumjs/core/strings
+ */
 const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types')
 
 /**
@@ -8,7 +11,8 @@ const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types')
  * 2. If `Intl` exists it will be used.
  * 3. If neither of those exist, uses `'en-US'` as a default.
  * 
- * @returns string - The locale/language string.
+ * @returns {string} - The locale/language string.
+ * @alias module:@lumjs/core/strings.getLocale
  */
 function getLocale()
 {
@@ -42,7 +46,8 @@ exports.getLocale = getLocale;
  * @param {boolean} [lcrest=false] Make the rest of the string lowercase? 
  * @param {string} [locale=getLocale()] The locale/language of the string.
  * 
- * @returns string - The output string.
+ * @returns {string} - The output string.
+ * @alias module:@lumjs/core/strings.ucfirst
  */
 function ucfirst ([ first, ...rest ], lcrest = false, locale = getLocale())
 {
@@ -61,11 +66,13 @@ exports.ucfirst = ucfirst;
  * Make the first character of each *word* in a string uppercase.
  *  
  * @param {string} string - The input string. 
- * @param {boolean} [unicode=false] Use Unicode words? (Only uses ASCII words otherwise)
+ * @param {boolean} [unicode=false] Use *Unicode* words? 
+ *   Only uses simple *PCRE-style* words (`\w`) otherwise.
  * @param {boolean} [lcrest=false] Make the rest of each word lowercase? 
  * @param {string} [locale=getLocale()] The locale/language of the string. 
  * 
  * @returns {string} - The output string.
+ * @alias module:@lumjs/core/strings.ucwords
  */
 function ucwords(string, unicode = false, lcrest = false, locale = getLocale())
 {
@@ -77,6 +84,12 @@ exports.ucwords = ucwords;
 
 /**
  * Is the passed in value a valid `String.replace` search value.
+ * 
+ * Only strings and `RegExp` objects are valid.
+ * 
+ * @param {*} v - Value to check.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/strings.isSearch
  */
 function isSearch(value)
 {
@@ -87,6 +100,12 @@ exports.isSearch = isSearch;
 
 /**
  * Is the passed in value a valid `String.replace` replacement value.
+ * 
+ * Only strings and functions are valid.
+ * 
+ * @param {*} v - Value to check.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/strings.isReplacement
  */
 function isReplacement(value)
 {
@@ -95,6 +114,26 @@ function isReplacement(value)
 
 exports.isReplacement = isReplacement;
 
+/**
+ * Apply multiple replacement rules to a string.
+ * 
+ * @param {string} string - The input string.
+ * @param {object} replacements - Replacement rules.
+ * 
+ *   If this is an `Array` then each item in the array can be:
+ *   - Another array with two items, `[find, replace]`;
+ *   - A `boolean`, will change the current `useAll` settting.
+ * 
+ *   If this is any other kind of `object` then the enumerable
+ *   property *keys* will be used as `find` strings, and the 
+ *   associated *values* will be used as the `replacement` values.
+ * 
+ * @param {boolean} [useAll] Which replacement method will be used.
+ *   If `true` we use `replaceAll()`, if `false` we use `replace()`.
+ *   The default is `false` if `value` is an `Array`, or `true` otherwise.
+ * @returns {string} The output string with all replacements performed.
+ * @alias module:@lumjs/core/strings.replaceItems
+ */
 function replaceItems(string, replacements, useAll)
 {
   needType(S, string);

package/lib/types/basics.js

@@ -4,6 +4,7 @@ const {O, F, S, SY} = require('./js');
  * See if a value is a non-null `object`.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.isObj
  */
  function isObj(v) { return (typeof v === O && v !== null); }
 
@@ -12,6 +13,7 @@ const {O, F, S, SY} = require('./js');
   * Like `isObj()`, `null` does not count as an `object`.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isComplex
   */
  function isComplex(v) { return (typeof v === F || isObj(v)); }
  
@@ -19,6 +21,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is *nil* (i.e. either `null` or `undefined`).
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isNil
   */
  function isNil(v) { return (v === undefined || v === null); }
  
@@ -26,6 +29,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is not *nil* (i.e. neither `null` nor `undefined`).
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.notNil
   */
  function notNil(v) { return (v !== undefined && v !== null); }
  
@@ -35,14 +39,17 @@ const {O, F, S, SY} = require('./js');
   * is neither *nil* nor *complex*.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isScalar
   */
  function isScalar(v) { return (notNil(v) && !isComplex(v)); }
  
  /**
   * See if a value is an `Array` object.
   * This is literally just a copy of `Array.isArray`.
+  * @function
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isArray
   */
  const isArray = Array.isArray;
  
@@ -50,6 +57,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is a `TypedArray` object.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isTypedArray
   */
  function isTypedArray(v)
  {
@@ -62,6 +70,7 @@ const {O, F, S, SY} = require('./js');
   * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
   *   If `false` (default) we want a regular `Array`.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.nonEmptyArray
   */
  function nonEmptyArray(v, typed=false)
  {
@@ -75,6 +84,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is an `arguments` object.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isArguments
   */
  function isArguments(v) 
  {
@@ -85,6 +95,7 @@ const {O, F, S, SY} = require('./js');
  * See if a value is a Property name.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.isProperty
  */
 function isProperty(v)
 {
@@ -109,6 +120,7 @@ function isProperty(v)
  * 
  * @param {object} obj - The object we are testing. 
  * @returns {boolean} - Is the object a valid descriptor?
+ * @alias module:@lumjs/core/types.doesDescriptor
  */
  function doesDescriptor(obj)
  {

package/lib/types/def.js

@@ -4,6 +4,9 @@ const {F, B} = require('./js');
 const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
 const copy = require('../obj/copyall');
 
+// A really really cheap version of clone().
+const clone = obj => copy({}, obj);
+
 /**
  * A wrapper around `Object.defineProperty()`.
  * 
@@ -12,16 +15,22 @@ const copy = require('../obj/copyall');
  * 
  * @param {(object|function)} obj - The object to add a property to.
  * @param {?(string|boolean|object)} name - If a `string`, the property name.
+ *   Property names may also be `symbol` values.
  * 
  *   If this is `null` or `undefined` then the `value` is ignored entirely,
  *   and instead a bound version of this function is created with the
- *   `obj` already passed as the first parameter. Can be useful if you
- *   need to add a lot of properties to the same object.
+ *   `obj` already passed as the first parameter, and any of the options from
+ *   `opts` added to a new default set of options bound to the function.
+ *   Can be useful if you need to add a lot of properties to the same object.
  * 
  *   If this is a `boolean`, then the same logic as if it was `null` or 
  *   `undefined` will apply, except that an `enumerable` property with this 
  *   value will also be added to the descriptors.
  * 
+ *   If this is an `object`, we also ignore `value` entirely, as each of 
+ *   the keys of this object will be used as the name of a property, 
+ *   and the value associated with the key will be the value to assign it.
+ * 
  * @param {*} value - Used to determine the value of the property.
  * 
  *   If it is an a valid descriptor object (as per `doesDescriptor()`),
@@ -29,31 +38,29 @@ const copy = require('../obj/copyall');
  *   property defined, one will be added, and will be set to `true`.
  *   This behaviour may be overridden by the `opts` parameter.
  * 
- *   If this is a `function` and `opts` is a `boolean` or `function`,
- *   then this will be used as a getter or setter (see `opts` for details.)
+ *   If this and `opts` are both `function` values, then this will
+ *   be used as a *getter*, and `opts` will be used a *setter*.
  * 
  *   Any other value passed here will be used as the `value` in a
  *   pre-canned descriptor, also with `configurable` set to `true`.
  * 
- * @param {(object|function|boolean)} [opts] - A multi-purpose option.
+ * @param {*} [opts] - A multi-purpose option.
  * 
  *   If this is an `object` then it is reserved for named options.
- *   Any other use of this is dependent on the `value` parameter.
+ *   The named options `configurable`, `enumerable`, and `writable`
+ *   can be used to define default values to the descriptor properties
+ *   of the same name.
  * 
  *   If `value` and this are both `function` values, then `value` will
  *   be used as a *getter* and this will be used as a *setter*.
  * 
- *   If `value` is a `function` and this is `true`, then `value` will
- *   be used as a *getter* and no *setter* will be assigned.
- * 
- *   If `value` is a `function` and this is `false`, then `value` will
- *   be used as a *setter* and no *getter* will be assigned.
- * 
  *   If `value` is a valid descriptor object, then setting this to `false`
  *   will disable the assumption that it is the descriptor to set.
  *   Setting this to `true` on will instruct the function to make a clone 
  *   of the descriptor object before modifying any properties in it.
  * 
+ *   This defaults to `undefined`, except if 
+ * 
  * @returns {*} Normally the `obj` argument with new property added.
  * 
  *   The exception is if this is a bound copy of the function created
@@ -66,6 +73,7 @@ const copy = require('../obj/copyall');
  *   def(myObj)('name', "Bob")('age', 42);
  * ```
  * 
+ * @alias module:@lumjs/core/types.def
  */
 function def(obj, name, value, opts)
 {
@@ -132,17 +140,12 @@ function def(obj, name, value, opts)
 
   if (opts !== false && doesDescriptor(value))
   { // The value is a descriptor, let's use it.
-    desc = (opts === true) ? copy(value) : value;
+    desc = (opts === true) ? clone(value) : value;
   }
   else if (typeof value === F && typeof opts === F)
   { // A getter and setter were both specified.
     desc = {get: value, set: opts};
   }
-  else if (typeof value === F && typeof opts === B)
-  { // A function value with a boolean opts is a getter or setter.
-    const prop = opts ? 'get' : 'set';
-    desc = {[prop]: value};
-  }
   else 
   { // The value is just a value, so let's assign it.
     desc = {value};