Auto generate docs (#2315)

* Auto generate docs

Docs can be generatred by running yarn run gen-doc
Add jsdoc and jsdoc2md dev dependencies

* Add tests to NavigationOption params

* fix tests

* Fix e2e and implement missing classes after rebase

* f

docs/docs/Navigation.md

@@ -0,0 +1,53 @@
+<a name="Navigation"></a>
+
+## Navigation
+
+* [Navigation](#Navigation)
+    * [.registerContainer(containerName, getContainerFunc)](#Navigation+registerContainer)
+    * [.setRoot(root)](#Navigation+setRoot)
+    * [.setOptions(containerId, options)](#Navigation+setOptions)
+
+
+* * *
+
+<a name="Navigation+registerContainer"></a>
+
+### navigation.registerContainer(containerName, getContainerFunc)
+Every screen component in your app must be registered with a unique name. The component itself is a traditional React component extending React.Component.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| containerName | <code>string</code> | Unique container name |
+| getContainerFunc | <code>function</code> | generator function, typically `() => require('./myContainer')` |
+
+
+* * *
+
+<a name="Navigation+setRoot"></a>
+
+### navigation.setRoot(root)
+Reset the navigation stack to a new screen (the stack root is changed).
+
+
+| Param | Type |
+| --- | --- |
+| root | <code>Root</code> | 
+
+
+* * *
+
+<a name="Navigation+setOptions"></a>
+
+### navigation.setOptions(containerId, options)
+Change a containers navigation options
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| containerId | <code>string</code> | Unique container name |
+| options | <code>NavigationOptions</code> |  |
+
+
+* * *
+

docs/templates/docs.hbs

@@ -0,0 +1,5 @@
+{{>header~}}
+{{>body}}
+{{>member-index~}}
+{{>separator~}}
+{{>members~}}

lib/src/Navigation.js

@@ -9,7 +9,10 @@ const LayoutTreeCrawler = require('./commands/LayoutTreeCrawler');
 const PrivateEventsListener = require('./events/PrivateEventsListener');
 const PublicEventsRegistry = require('./events/PublicEventsRegistry');
 const Element = require('./adapters/Element');
+const Root = require('./params/Root');
+const NavigationOptions = require('./params/NavigationOptions');
 
+/** @constructor */
 class Navigation {
   constructor() {
     this.store = new Store();
@@ -25,20 +28,35 @@ class Navigation {
     this.privateEventsListener.listenAndHandlePrivateEvents();
     this.Element = Element;
   }
+
+  /**
+   * Every screen component in your app must be registered with a unique name. The component itself is a traditional React component extending React.Component.
+   * @param {string} containerName Unique container name
+   * @param {function} getContainerFunc generator function, typically `() => require('./myContainer')`
+   */
   registerContainer(containerName, getContainerFunc) {
     this.containerRegistry.registerContainer(containerName, getContainerFunc);
   }
 
+  /**
+   * Reset the navigation stack to a new screen (the stack root is changed).
+   * @param {Root} root
+   */
   setRoot(params) {
-    return this.commands.setRoot(params);
+    return this.commands.setRoot(new Root(params));
   }
 
   setDefaultOptions(options) {
     this.commands.setDefaultOptions(options);
   }
 
+  /**
+   * Change a containers navigation options
+   * @param {string} containerId Unique container name
+   * @param {NavigationOptions} options
+   */
   setOptions(containerId, options) {
-    this.commands.setOptions(containerId, options);
+    this.commands.setOptions(containerId, new NavigationOptions(options));
   }
 
   showModal(params) {

lib/src/params/BottomTabs.js

@@ -0,0 +1,19 @@
+const { forEach } = require('lodash');
+const Container = require('./Container');
+
+class BottomTabs {
+  /**
+   * @constructor
+   * @typedef {Object} BottomTabs
+   * @property {Container[]} tabs
+   */
+  constructor(tabs) {
+    if (!tabs || tabs.length === 0) {
+      throw new Error('BottomTabs undefined');
+    }
+    this.tabs = [];
+    forEach(tabs, (tab) => this.tabs.push({ container: new Container(tab.container) }));
+  }
+}
+
+module.exports = BottomTabs;

lib/src/params/BottomTabs.test.js

@@ -0,0 +1,34 @@
+const BottomTabs = require('./BottomTabs');
+
+const TAB1 = {
+  container: {
+    name: 'navigation.playground.TextScreen',
+    passProps: {
+      text: 'This is a side menu center screen tab 2'
+    }
+  }
+};
+const TAB2 = {
+  container: {
+    name: 'navigation.playground.TextScreen',
+    passProps: {
+      text: 'This is a side menu center screen tab 1'
+    }
+  }
+};
+const TABS = [TAB1, TAB2];
+
+describe('ContainerRegistry', () => {
+  it('parses tabs correctly', () => {
+    const uut = new BottomTabs(TABS);
+    expect(uut.tabs.length).toBe(2);
+  });
+
+  it('throws if tabs are undefined', () => {
+    expect(() => new BottomTabs()).toThrowError('BottomTabs undefined');
+  });
+
+  it('throws if zero tabs', () => {
+    expect(() => new BottomTabs([])).toThrowError('BottomTabs undefined');
+  });
+});

lib/src/params/Button.js

@@ -0,0 +1,16 @@
+class Button {
+  /**
+   * @property {String} id
+   * @property {string} [testID]
+   * @property {string} [title]
+   * @property {string} [color]
+   */
+  constructor(params) {
+    this.id = params.id;
+    this.testID = params.testID;
+    this.title = params.title;
+    this.color = params.color;
+  }
+}
+
+module.exports = Button;

lib/src/params/Button.test.js

@@ -0,0 +1,18 @@
+const Button = require('./Button');
+
+const BUTTON = {
+  id: 'myBtn',
+  testID: 'BTN',
+  title: 'My Button',
+  color: 'red'
+};
+
+describe('Button', () => {
+  it('parses button', () => {
+    const uut = new Button(BUTTON);
+    expect(uut.id).toEqual('myBtn');
+    expect(uut.testID).toEqual('BTN');
+    expect(uut.title).toEqual('My Button');
+    expect(uut.color).toEqual('red');
+  });
+});

lib/src/params/Container.js

@@ -0,0 +1,16 @@
+class Container {
+  /**
+   * @typedef {Object} Container
+   * @property {string} name The container's registered name
+   * @property {Object} [passProps] props
+   */
+  constructor(params) {
+    if (!params || !params.name) {
+      throw new Error('Container name is undefined');
+    }
+    this.name = params.name;
+    this.passProps = params.passProps;
+  }
+}
+
+module.exports = Container;

lib/src/params/Container.test.js

@@ -0,0 +1,21 @@
+const Container = require('./Container');
+
+const PASS_PROPS = {
+  number: 9
+};
+const CONTAINER = {
+  name: 'myScreen',
+  passProps: PASS_PROPS
+};
+
+describe('ContainerRegistry', () => {
+  it('parses container correctly', () => {
+    const uut = new Container(CONTAINER);
+    expect(uut.name).toBe('myScreen');
+    expect(uut.passProps).toEqual(PASS_PROPS);
+  });
+
+  it('throws if container name is missing', () => {
+    expect(() => new Container()).toThrowError('Container name is undefined');
+  });
+});

lib/src/params/NavigationOptions.js

@@ -0,0 +1,32 @@
+const TopBar = require('./TopBar');
+const TabBar = require('./TabBar');
+const Button = require('./Button');
+
+ /**
+ * A module for adding two values.
+ * @module NavigationOptions
+ */
+
+ /**
+  * NavigationOptions are used by containers to customize their behavior and style.
+  * @alias module:NavigationOptions
+  */
+class NavigationOptions {
+  /**
+   * @typedef {Object} NavigationOptions
+   * @property {TopBar} topBar
+   * @property {TabBar} bottomTabs
+   * @property {String} [orientation]
+   * @property {Button} [rightButtons]
+   * @property {Button} [leftButtons]
+   */
+  constructor(options) {
+    this.topBar = options.topBar && new TopBar(options.topBar);
+    this.bottomTabs = options.bottomTabs && new TabBar(options.bottomTabs);
+    this.orientation = options.orientation;
+    this.rightButtons = options.rightButtons && options.rightButtons.map((button) => new Button(button));
+    this.leftButtons = options.leftButtons && options.leftButtons.map((button) => new Button(button));
+  }
+}
+
+module.exports = NavigationOptions;

lib/src/params/NavigationOptions.test.js

@@ -0,0 +1,40 @@
+const NavigationOptions = require('./NavigationOptions');
+const TabBar = require('./TabBar');
+const TopBar = require('./TopBar');
+
+const TAB_BAR = {};
+const TOP_BAR = {};
+const RIGHT_BUTTONS = [
+  {
+    id: 'myBtn',
+    testID: 'BTN',
+    title: 'My Button',
+    color: 'red'
+  }
+];
+const LEFT_BUTTONS = [
+  {
+    id: 'myBtn',
+    testID: 'BTN',
+    title: 'My Button',
+    color: 'red'
+  }
+];
+const NAVIGATION_OPTIONS = {
+  topBar: TOP_BAR,
+  bottomTabs: TAB_BAR,
+  orientation: 'portrait',
+  rightButtons: RIGHT_BUTTONS,
+  leftButtons: LEFT_BUTTONS
+};
+
+describe('NavigationOptions', () => {
+  it('parses navigationOptions correctly', () => {
+    const uut = new NavigationOptions(NAVIGATION_OPTIONS);
+    expect(uut.bottomTabs).toBeInstanceOf(TabBar);
+    expect(uut.topBar).toBeInstanceOf(TopBar);
+    expect(uut.orientation).toEqual('portrait');
+    expect(uut.rightButtons).toEqual(RIGHT_BUTTONS);
+    expect(uut.leftButtons).toEqual(LEFT_BUTTONS);
+  });
+});

lib/src/params/Root.js

@@ -0,0 +1,19 @@
+const Container = require('./Container');
+const SideMenu = require('./SideMenu');
+const BottomTabs = require('./BottomTabs');
+
+class Root {
+  /**
+   * @typedef {Object} Root
+   * @property {Container} container
+   * @property {SideMenu} [sideMenu]
+   * @property {BottomTabs} [bottomTabs]
+   */
+  constructor(root) {
+    this.container = root.container && new Container(root.container);
+    this.sideMenu = root.sideMenu && new SideMenu(root.sideMenu);
+    this.bottomTabs = root.bottomTabs && new BottomTabs(root.bottomTabs).tabs;
+  }
+}
+
+module.exports = Root;

lib/src/params/Root.test.js

@@ -0,0 +1,83 @@
+const Root = require('./Root');
+
+const CONTAINER = { name: 'myScreen' };
+const SIDE_MENU = {
+  left: {
+    container: {
+      name: 'navigation.playground.TextScreen',
+      passProps: {
+        text: 'This is a left side menu screen'
+      }
+    }
+  },
+  right: {
+    container: {
+      name: 'navigation.playground.TextScreen',
+      passProps: {
+        text: 'This is a right side menu screen'
+      }
+    }
+  }
+};
+const BOTTOM_TABS = [
+  {
+    container: {
+      name: 'navigation.playground.TextScreen',
+      passProps: {
+        text: 'This is a side menu center screen tab 1'
+      }
+    }
+  },
+  {
+    container: {
+      name: 'navigation.playground.TextScreen',
+      passProps: {
+        text: 'This is a side menu center screen tab 2'
+      }
+    }
+  },
+  {
+    container: {
+      name: 'navigation.playground.TextScreen',
+      passProps: {
+        text: 'This is a side menu center screen tab 3'
+      }
+    }
+  }
+];
+
+describe('Root', () => {
+  it('Parses Root', () => {
+    const uut = new Root(simpleRoot());
+    expect(uut.container.name).toEqual(CONTAINER.name);
+  });
+
+  it('parses root with sideMenu', () => {
+    const uut = new Root(rootWithSideMenu());
+    expect(uut.container.name).toEqual(CONTAINER.name);
+    expect(uut.sideMenu).toEqual(SIDE_MENU);
+  });
+
+  it('parses root with BottomTabs', () => {
+    const uut = new Root(rootWithBottomTabs());
+    expect(uut.bottomTabs).toEqual(BOTTOM_TABS);
+  });
+});
+
+function rootWithBottomTabs() {
+  return {
+    container: CONTAINER,
+    bottomTabs: BOTTOM_TABS
+  };
+}
+
+function simpleRoot() {
+  return { container: CONTAINER };
+}
+
+function rootWithSideMenu() {
+  return {
+    container: CONTAINER,
+    sideMenu: SIDE_MENU
+  };
+}

lib/src/params/SideMenu.js

@@ -0,0 +1,15 @@
+const Container = require('./Container');
+
+class SideMenu {
+  /**
+  * @typedef {Object} SideMenu
+  * @property {Container} [left]
+  * @property {Container} [right]
+  */
+  constructor(params) {
+    this.left = params.left && { container: new Container(params.left.container) };
+    this.right = params.right && { container: new Container(params.right.container) };
+  }
+}
+
+module.exports = SideMenu;

lib/src/params/SideMenu.test.js

@@ -0,0 +1,13 @@
+const SideMenu = require('./SideMenu');
+
+const LEFT = { container: { name: 'myLeftScreen' } };
+const RIGHT = { container: { name: 'myRightScreen' } };
+const SIDE_MENU = { left: LEFT, right: RIGHT };
+
+describe('SideMenu', () => {
+  it('parses SideMenu', () => {
+    const uut = new SideMenu(SIDE_MENU);
+    expect(uut.left).toEqual(LEFT);
+    expect(uut.right).toEqual(RIGHT);
+  });
+});

lib/src/params/TabBar.js

@@ -0,0 +1,24 @@
+const { isEmpty } = require('lodash');
+
+class TabBar {
+  /**
+   * @typedef {Object} TabBar
+   * @property {string} [currentTabId]
+   * @property {number} [currentTabIndex]
+   * @property {number} [tabBadge]
+   * @property {boolean} [hidden]
+   * @property {boolean} [animateHide]
+   */
+  constructor(params) {
+    if (isEmpty(params)) {
+      return;
+    }
+    this.currentTabId = params.currentTabId;
+    this.currentTabIndex = params.currentTabIndex;
+    this.tabBadge = params.tabBadge;
+    this.hidden = params.hidden;
+    this.animateHide = params.animateHide;
+  }
+}
+
+module.exports = TabBar;

lib/src/params/TabBar.test.js

@@ -0,0 +1,20 @@
+const TabBar = require('./TabBar');
+
+const TAB_BAR = {
+  currentTabId: 1,
+  currentTabIndex: 2,
+  tabBadge: 3,
+  hidden: true,
+  animateHide: true
+};
+
+describe('TabBar', () => {
+  it('parses TabBar options', () => {
+    const uut = new TabBar(TAB_BAR);
+    expect(uut.currentTabId).toEqual(1);
+    expect(uut.currentTabIndex).toEqual(2);
+    expect(uut.tabBadge).toEqual(3);
+    expect(uut.hidden).toEqual(true);
+    expect(uut.animateHide).toEqual(true);
+  });
+});

lib/src/params/TopBar.js

@@ -0,0 +1,27 @@
+class TopBar {
+  /**
+   * @typedef {Object} TopBar
+   * @property {string} [title]
+   * @property {color} [backgroundColor]
+   * @property {color} [textColor]
+   * @property {number} [textFontSize]
+   * @property {string} [textFontFamily]
+   * @property {boolean} [hidden]
+   * @property {boolean} [animateHide]
+   * @property {boolean} [hideOnScroll]
+   * @property {boolean} [transparent]
+   */
+  constructor(options) {
+    this.title = options.title;
+    this.backgroundColor = options.backgroundColor;
+    this.textColor = options.textColor;
+    this.textFontSize = options.textFontSize;
+    this.textFontFamily = options.textFontFamily;
+    this.hidden = options.hidden;
+    this.animateHide = options.animateHide;
+    this.hideOnScroll = options.hideOnScroll;
+    this.transparent = options.transparent;
+  }
+}
+
+module.exports = TopBar;

lib/src/params/TopBar.test.js

@@ -0,0 +1,28 @@
+const TopBar = require('./TopBar');
+
+const TOP_BAR = {
+  title: 'something',
+  backgroundColor: 'red',
+  textColor: 'green',
+  textFontSize: 13,
+  textFontFamily: 'guttmanYadBrush',
+  hidden: true,
+  animateHide: true,
+  hideOnScroll: true,
+  transparent: true
+};
+
+describe('TopBar', () => {
+  it('Parses TopBar', () => {
+    const uut = new TopBar(TOP_BAR);
+    expect(uut.title).toEqual('something');
+    expect(uut.backgroundColor).toEqual('red');
+    expect(uut.textColor).toEqual('green');
+    expect(uut.textFontSize).toEqual(13);
+    expect(uut.textFontFamily).toEqual('guttmanYadBrush');
+    expect(uut.hidden).toEqual(true);
+    expect(uut.animateHide).toEqual(true);
+    expect(uut.hideOnScroll).toEqual(true);
+    expect(uut.transparent).toEqual(true);
+  });
+});

package.json

@@ -38,7 +38,8 @@
     "test-e2e-ios": "node ./scripts/test.e2e.ios.js",
     "test-all": "node ./scripts/test.all.js",
     "test-watch": "jest --coverage --watch",
-    "release": "node ./scripts/release.js"
+    "release": "node ./scripts/release.js",
+    "gen-doc": "node ./scripts/generate-js-doc.js"
   },
   "peerDependencies": {
     "react": "*",
@@ -49,21 +50,23 @@
     "prop-types": "15.x.x"
   },
   "devDependencies": {
-    "xo": "0.18.x",
+    "detox": "6.x.x",
     "eslint-config-xo": "0.18.x",
     "eslint-config-xo-react": "0.13.x",
     "eslint-plugin-react": "7.x.x",
-    "detox": "6.x.x",
     "jest": "21.x.x",
-    "mocha": "3.x.x",
+    "jsdoc": "3.x.x",
+    "jsdoc-to-markdown": "3.x.x",
+    "mocha": "4.x.x",
     "react": "16.0.0-alpha.6",
     "react-native": "0.44.2",
+    "react-redux": "5.x.x",
     "react-test-renderer": "16.0.0-alpha.6",
-    "remx": "2.x.x",
     "redux": "3.x.x",
-    "react-redux": "5.x.x",
+    "remx": "2.x.x",
     "semver": "5.x.x",
-    "shell-utils": "1.x.x"
+    "shell-utils": "1.x.x",
+    "xo": "0.18.x"
   },
   "babel": {
     "env": {

scripts/generate-js-doc.js

@@ -0,0 +1,38 @@
+const jsdoc2md = require('jsdoc-to-markdown');
+const fs = require('fs');
+const path = require('path');
+
+const inputFiles = ['./lib/src/params/NavigationOptions.js', './lib/src/Navigation.js'];
+const outputDir = './docs/docs/';
+const partial = ['./docs/templates/scope.hbs', './docs/templates/docs.hbs'];
+
+const generateMarkdownForFile = (file) => {
+  const templateData = jsdoc2md.getTemplateDataSync({ files: file });
+  const classNames = getClassesInFile(templateData);
+  classNames.forEach((className) => createDocFileForClass(className, templateData));
+};
+
+function getClassesInFile(templateData) {
+  const classNames = templateData.reduce((classNames, identifier) => {
+    if (identifier.kind === 'class') {
+      classNames.push(identifier.name);
+    }
+    return classNames;
+  }, []);
+  return classNames;
+}
+
+function createDocFileForClass(className, templateData) {
+  const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`;
+  const options = {
+    data: templateData,
+    template,
+    separators: true,
+    partial
+  };
+  console.log(`rendering ${className}, template: ${template}`);
+  const output = jsdoc2md.renderSync(options);
+  fs.writeFileSync(path.resolve(outputDir, `${className}.md`), output);
+}
+
+inputFiles.forEach((inputFile) => generateMarkdownForFile(inputFile));