chore(docs): clean up broken/messy examples

dvdzkwsk · Dec 24, 2016 · a7593cf · a7593cf
1 parent b31293b
commit a7593cf
Show file tree

Hide file tree

Showing 24 changed files with 69 additions and 58 deletions.
diff --git a/docs/scripts/build-docs.js b/docs/scripts/build-docs.js
@@ -12,6 +12,7 @@ const rendered = renderToStaticMarkup(r(App, { functions: docs.api }))
 const html = '<!doctype html>' + renderToStaticMarkup(r(HTML, {
   scripts: [
     { inject: true, content: [
+      fs.readFileSync(path.resolve(__dirname, '../../dist/installer.min.js'), 'utf8'),
       fs.readFileSync(path.resolve(__dirname, '../src/main.js'), 'utf8'),
     ].join('') },
   ],

diff --git a/docs/src/components/App.js b/docs/src/components/App.js
@@ -3,7 +3,7 @@ const marked = require('marked')
 
 const CodeExample = ({ children }) =>
   r.pre(null,
-    r.code(null, children))
+    r.code({ className: 'code-example' }, children))
 
 const FunctionDoc = ({
   name,

diff --git a/docs/src/components/HTML.js b/docs/src/components/HTML.js
@@ -1,18 +1,20 @@
 const r = require('../lib/react')
 
-const Script = ({ src, inject, content }) =>
-  inject ? r.script(null, content) : r.script({ src })
+const Script = ({ src, inject, content }) => inject
+   ? r.script({ dangerouslySetInnerHTML: { __html: content } })
+   : r.script({ src })
 
-const Style = ({ href, inject, content }) =>
-  inject ? r.style(null, content) : r.link({ href, rel: 'stylesheet' })
+const Style = ({ href, inject, content }) => inject
+  ? r.style({ dangerouslySetInnerHTML: { __html: content } })
+  : r.link({ href, rel: 'stylesheet' })
 
 const HTML = ({
   children,
   title,
   scripts = [],
   styles = [],
 }) =>
-  r.html(null,
+  r.html({ className: 'no-js' },
     r.head(null,
       r.title(null, title),
       r.meta({ charSet: 'utf-8' }),

diff --git a/docs/src/lib/react.js b/docs/src/lib/react.js
@@ -5,7 +5,7 @@ forEach(tag => r[tag] = (...args) => r(tag, ...args),
         ['html', 'head', 'title', 'link', 'script', 'style', 'meta', 'body', 'div',
          'main', 'nav', 'article', 'section', 'p', 'span', 'ul', 'ol', 'li',
          'a', 'img', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'code', 'pre',
-         'link', 'script', 'meta'])
+         'link', 'script', 'noscript', 'meta'])
 /* eslint-enable */
 
 module.exports = r
diff --git a/docs/src/main.js b/docs/src/main.js
@@ -0,0 +1,16 @@
+;(function () {
+  redash(window) // eslint-disable-line
+  window.klipse_settings = {
+    selector_eval_js: '.code-example',
+  }
+
+  function loadScript (src) {
+    const script = document.createElement('script')
+    script.src = src
+    document.body.appendChild(script)
+  }
+
+  window.addEventListener('load', function () {
+    loadScript('https://cdn.zuko.me/klipse.js')
+  })
+})()
diff --git a/src/append.js b/src/append.js
@@ -3,11 +3,13 @@ import _curry2 from './internal/_curry2'
 
 /**
  * @name append
- * @signature a -> [a] -> [a] | String -> String -> String
+ * @signature
+ * a -> [a] -> [a]
+ * String -> String -> String
  * @since v0.10.0
  * @description
- * Appends a single element to a list. If the second argument is a string,
- * string concatenation will be used instead.
+ * Appends a single element to a list. If the argument in list position is a
+ * string, string concatenation will be used instead.
  * @see prepend
  * @see concat
  *

diff --git a/src/compose.js b/src/compose.js
@@ -25,13 +25,9 @@ import pipe from './pipe'
  * // to the next function, `isEven`. Because `isEven` is the last function in
  * // the composition, its result is the final return value.
  * // This would look like: (x) => isEven(sqrt(x))
- * const isSqrtEven = compose([isEven, sqrt])
+ * const isSqrtEven = compose([isEven, Math.sqrt])
  *
- * isSqrtEven(9)  // => false
  * isSqrtEven(16) // => true
- *
- * // You can compose more than two functions at a time
- * compose([equals(4), sqrt, double])(8) // => true
  */
 export default function compose (fns) {
   var i = 0

diff --git a/src/dissoc.js b/src/dissoc.js
@@ -13,11 +13,6 @@ import _curry2 from './internal/_curry2'
  * @example
  * const user = { first: 'Bob', last: 'Loblaw' }
  * dissoc('first', user) // => { last: 'Loblaw' }
- * @example
- * const user = { first: 'Bob', last: 'Loblaw' }
- * const newUser = dissoc('age', user) // => { first: 'Bob', last: 'Loblaw' }
- *
- * user === newUser // => false
  */
 export default _curry2(function dissoc (k, kv) {
   var y = {}

diff --git a/src/drop.js b/src/drop.js
@@ -11,9 +11,6 @@ import _slice from './internal/_slice'
  *
  * @example
  * drop(2, [1, 2, 3, 4]) // => [3, 4]
- *
- * @example
- * drop(5, [1, 2, 3, 4]) // => []
  */
 export default _curry2(function drop (n, xs) {
   return _slice.call(xs, n)

diff --git a/src/find.js b/src/find.js
@@ -11,8 +11,8 @@ import _curry2 from './internal/_curry2'
  *
  * @example
  * find(isEven, [1, 3, 4, 6]) // => 4
- * find(propEq('id', 2), [{ id: 1 }, { id : 2 }]) // => { id: 2 }
  * find(isEven, [1, 3, 5, 7]) // => undefined
+ * find(propEq('id', 2), [{ id: 1 }, { id : 2 }]) // => { id: 2 }
  */
 export default _curry2(function find (pred, xs) {
   var i   = 0

diff --git a/src/fmap.js b/src/fmap.js
@@ -8,6 +8,20 @@ import _curry2 from './internal/_curry2'
  * Lifts a function into a functor. The functor must implement either `fmap` or `map`.
  * @example
  * // Tree is a functor that implements `map` (or `fmap`):
+ * class Tree {
+ *   constructor (value, left, right) {
+ *      this._value = value
+ *      this._left = left
+ *      this._right = right
+ *   }
+ *   map (fn) {
+ *     return new Tree(
+ *       fn(this._value),
+ *       this._left && this._left.map(fn),
+ *       this._right && this._right.map(fn),
+ *     )
+ *   }
+ * }
  * const tree = new Tree(2, new Tree(1), new Tree(3))
  * fmap(double, tree) // => Tree(4, Tree(2), Tree(6))
  *

diff --git a/src/has.js b/src/has.js
@@ -12,7 +12,7 @@ import _hasOwn from './internal/_hasOwn'
  * has('name', { name: 'Bill' }) // => true
  *
  * // Ignores inherited properties
- * class A () {
+ * class A {
  *   foo () {}
  * }
  * const a = new A()

diff --git a/src/head.js b/src/head.js
@@ -8,7 +8,6 @@
  *
  * @example
  * head([1, 2, 3, 4]) // => [1]
- * head([])           // => undefined
  */
 export default function head (xs) {
   return xs[0]

diff --git a/src/identity.js b/src/identity.js
@@ -9,7 +9,7 @@
  * @example
  * identity(5) // => 5
  *
- * const doubleIfEven = ifElse(isEven, double, identity)
+ * const doubleIfEven = when(isEven, multiply(2))
  * doubleIfEven(2) // => 4
  * doubleIfEven(3) // => 3
  */

diff --git a/src/juxt.js b/src/juxt.js
@@ -9,8 +9,8 @@ import map from './map'
  * contains the result of each function call in its corresponding position.
  *
  * @example
- * juxt([inc, dec, multiply(3)])(2) => [3, 1, 6]
- * juxt([add, divide, multiply])(2, 4) => [6, 2, 8]
+ * juxt([inc, dec, multiply(3)])(2)    // => [3, 1, 6]
+ * juxt([add, divide, multiply])(2, 4) // => [6, 2, 8]
  */
 export default function juxt (fns) {
   return function () {

diff --git a/src/last.js b/src/last.js
@@ -3,13 +3,13 @@
  * @signature [a] -> a
  * @since v0.1.0
  * @description
- * Returns the last element in a list.
+ * Returns the last element in a list. If the list is empty, `undefined` is
+ * returned.
  * @see head
  * @see tail
  *
  * @example
  * last([1, 2, 3, 4]) // => 4
- * last([])           // => undefined
  */
 export default function last (xs) {
   return xs[xs.length - 1]

diff --git a/src/length.js b/src/length.js
@@ -7,7 +7,6 @@
  *
  * @example
  * length([1, 2, 3, 4, 5]) // => 5
- * length([])              // => 0
  */
 export default function length (xs) {
   return xs.length

diff --git a/src/lensProp.js b/src/lensProp.js
@@ -17,9 +17,8 @@ import prop from './prop'
  * const nameLens = lensProp('name')
  * const bob = { name: 'Bob' }
  *
- * view(nameLens, bob)      // => 'Bob'
- * set(nameLes, 'Joe', bob) // => { name: 'Joe' }
- * console.log(bob)         // => { name: 'Bob' }
+ * view(nameLens, bob)       // => 'Bob'
+ * set(nameLens, 'Joe', bob) // => { name: 'Joe' }
  */
 export default function lensProp (key) {
   return lens(prop(key), assoc(key))

diff --git a/src/mapi.js b/src/mapi.js
@@ -12,8 +12,8 @@ import _curry2 from './internal/_curry2'
  * @see map
  *
  * @example
- * const xform = (x, idx) => idx % 2 === 0 ? x * 2 : x
- * mapIndexed(xform, [1, 2, 3, 4, 5]) => [2, 2, 6, 4, 5]
+ * const xform = (x, i) => isOdd(i) ? x * 2 : x
+ * mapi(xform, [1, 2, 3, 4, 5]) // => [2, 2, 6, 4, 5]
  */
 export default _curry2(function mapi (fn, as) {
   var bs  = new Array(as.length)

diff --git a/src/pipe.js b/src/pipe.js
@@ -18,11 +18,13 @@ import type from './type'
  * @see compose
  *
  * @example
- * const getFriends = pipe([prop('friends')
- *                          map(toUpper),
- *                          join(', ')])
+ * const getFriends = pipe([
+ *  prop('friends'),
+ *  map(pipe([prop('name'), toUpper])),
+ *  join(', ')
+ * ])
  *
- * const user = { friends: [{ name: 'Jim' }, { name: 'Dwight'}] }
+ * const user = { friends: [{ name: 'Jim' }, { name: 'Dwight' }] }
  * getFriends(user) // => 'JIM, DWIGHT'
  */
 export default function pipe (fns) {

diff --git a/src/prop.js b/src/prop.js
@@ -8,8 +8,8 @@ import _curry2 from './internal/_curry2'
  * Returns the value of a given property on an object.
  *
  * @example
- * prop('name', { name: 'Bob' }) // => Bob
  * prop('name', {})              // => undefined
+ * prop('name', { name: 'Bob' }) // => Bob
  */
 export default _curry2(function prop (k, o) {
   return o[k]

diff --git a/src/tap.js b/src/tap.js
@@ -4,26 +4,15 @@
  * @signature (a -> *) -> a -> a
  * @since v0.7.0
  * @description
- * Wraps a unary function so that it is called with the argument supplied to
- * it but its return value is ignored and the initial argument is returned
- * instead. This is useful when you want to perform a side effect without
+ * Wraps a unary function so that it is called as normal but its return value
+ * is ignored. This is useful when you want to perform a side effect without
  * interfering with an argument or composition.
  *
  * @example
  * const log = tap(x => console.log(x))
  *
  * // logs: 1, 2, 2, 4, 3, 6, 4, 8
- * map(pipe(log, double, log), [1, 2, 3, 4]) // => [2, 4, 6, 8]
- *
- * // Also useful when you want to step through a series of transformations
- * const trace = message => tap(x => console.log(message, x))
- *
- * fetchUser()                    // => Promise
- *  .then(trace('Got user'))      // => User, logs "Got user [data]"
- *  .then(getContacts)            // => Promise
- *  .then(trace('Got contacts'))  // => Array<User>, logs "Got contacts [data]"
- *  .then(map(prop('name')))      // => Array<String>
- *  .then(trace('Contact names')) // => Array<String>, logs "Contact names [data]"
+ * map(pipe([log, multiply(2), log]), [1, 2, 3, 4]) // => [2, 4, 6, 8]
  */
 export default function tap (fn) {
   return function (a) {

diff --git a/src/test.js b/src/test.js
@@ -9,7 +9,7 @@ import _curry2 from './internal/_curry2'
  *
  * @example
  * test(/bar/, 'foobarbaz') // => true
- * filter(test(/joe/i), ['Joe', 'Bill', 'joey'])) // => ['Joe', 'joey']
+ * filter(test(/joe/i), ['Joe', 'Bill', 'joey']) // => ['Joe', 'joey']
  */
 export default _curry2(function test (regex, str) {
   return regex.test(str)

diff --git a/src/without.js b/src/without.js
@@ -9,7 +9,7 @@ import _contains from './internal/_contains'
  * Excludes all elements of the first list from the second list.
  *
  * @example
- * without([1, 2], [1, 2, 3, 4, 2, 1, 7]) => [3, 4, 7]
+ * without([1, 2], [1, 2, 3, 4, 2, 1, 7]) // => [3, 4, 7]
  */
 export default _curry2(function without (as, bs) {
   var i   = 0