doc(docs): init #73

docs/index.md

+<a name="Wechaty"></a>
+
+## Wechaty
+Wechaty: Wechat for ChatBots.
+Connect ChatBots
+
+Class Wechaty
+
+Licenst: ISC
+https://github.com/zixia/wechaty
+
+**Kind**: global class  
+
+* [Wechaty](#Wechaty)
+    * _instance_
+        * [.state](#Wechaty+state)
+        * [.npmVersion](#Wechaty+npmVersion)
+        * [.puppet](#Wechaty+puppet)
+        * [.toString()](#Wechaty+toString)
+        * [.version([forceNpm])](#Wechaty+version) ⇒ <code>string</code>
+        * [.user()](#Wechaty+user)
+        * [.reset()](#Wechaty+reset)
+        * [.init()](#Wechaty+init)
+        * [.on()](#Wechaty+on)
+        * [.initPuppet()](#Wechaty+initPuppet)
+        * [.quit()](#Wechaty+quit)
+        * [.logout()](#Wechaty+logout)
+        * [.self()](#Wechaty+self)
+        * [.send()](#Wechaty+send)
+        * [.say()](#Wechaty+say)
+        * [.sleep()](#Wechaty+sleep)
+        * [.ding()](#Wechaty+ding)
+    * _static_
+        * [.instance()](#Wechaty.instance)
+
+<a name="Wechaty+state"></a>
+
+### wechaty.state
+the state
+
+**Kind**: instance property of <code>[Wechaty](#Wechaty)</code>  
+<a name="Wechaty+npmVersion"></a>
+
+### wechaty.npmVersion
+the npmVersion
+
+**Kind**: instance property of <code>[Wechaty](#Wechaty)</code>  
+<a name="Wechaty+puppet"></a>
+
+### wechaty.puppet
+TODO: support more events:
+2. send
+3. reply
+4. quit
+5. ...
+
+**Kind**: instance property of <code>[Wechaty](#Wechaty)</code>  
+<a name="Wechaty+toString"></a>
+
+### wechaty.toString()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+<a name="Wechaty+version"></a>
+
+### wechaty.version([forceNpm]) ⇒ <code>string</code>
+Return version of Wechaty
+
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Returns**: <code>string</code> - version number  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [forceNpm] | <code>boolean</code> | <code>false</code> | if set to true, will only return the version in package.json.                            otherwise will return git commit hash if .git exists. |
+
+**Example**  
+```js
+console.log(Wechaty.instance().version())
+ // #git[af39df]
+ console.log(Wechaty.instance().version(true))
+ // 0.7.9
+```
+<a name="Wechaty+user"></a>
+
+### wechaty.user()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+reset"></a>
+
+### wechaty.reset()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+<a name="Wechaty+init"></a>
+
+### wechaty.init()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+on"></a>
+
+### wechaty.on()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+initPuppet"></a>
+
+### wechaty.initPuppet()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+quit"></a>
+
+### wechaty.quit()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+logout"></a>
+
+### wechaty.logout()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+self"></a>
+
+### wechaty.self()
+get current user
+
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+<a name="Wechaty+send"></a>
+
+### wechaty.send()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+say"></a>
+
+### wechaty.say()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+sleep"></a>
+
+### wechaty.sleep()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty+ding"></a>
+
+### wechaty.ding()
+**Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Todo**
+
+- [ ] document me
+
+<a name="Wechaty.instance"></a>
+
+### Wechaty.instance()
+**Kind**: static method of <code>[Wechaty](#Wechaty)</code>  

package.json

@@ -18,6 +18,7 @@
     "ava": "ava --verbose --extension ts",
     "ts-node": "ts-node",
     "dist": "npm run clean && tsc && shx cp package.json dist/ && shx cp src/puppet-web/*.js dist/src/puppet-web/",
+    "doc": "npm run dist && jsdoc2md dist/src/wechaty.js > docs/index.md",
     "coverage": "nyc report --reporter=text-lcov | coveralls",
     "changelog": "github_changelog_generator -u wechaty -p wechaty && sed -i /greenkeeper/d CHANGELOG.md",
     "doctor": "npm run check-node-version && ts-node bin/doctor",
@@ -136,6 +137,7 @@
     "eslint-plugin-ava": "4.1.0",
     "finis": "0.0.2",
     "fluent-ffmpeg": "2.1.0",
+    "jsdoc-to-markdown": "^3.0.0",
     "nyc": "10.1.0",
     "qrcode-terminal": "0.11.0",
     "request": "2.79.0",

src/room.ts

-/**
- *
- * wechaty: Wechat for Bot. and for human who talk to bot/robot
- *
- * Licenst: ISC
- * https://github.com/zixia/wechaty
- *
- * Add/Del/Topic: https://github.com/wechaty/wechaty/issues/32
- *
- */
 import { EventEmitter } from 'events'
 
 import {
@@ -60,6 +50,16 @@ export type MemberQueryFilter = {
   alias?: string
 }
 
+/**
+ *
+ * wechaty: Wechat for Bot. and for human who talk to bot/robot
+ *
+ * Licenst: ISC
+ * https://github.com/zixia/wechaty
+ *
+ * Add/Del/Topic: https://github.com/wechaty/wechaty/issues/32
+ *
+ */
 export class Room extends EventEmitter implements Sayable {
   private static pool = new Map<string, Room>()
 
@@ -518,6 +518,9 @@ export class Room extends EventEmitter implements Sayable {
     return room
   }
 
+  /**
+   * @todo document me
+   */
   public static load(id: string): Room {
     if (!id) {
       throw new Error('Room.load() no id')

src/wechaty.ts

-/**
- *
- * Wechaty: Wechat for ChatBots.
- * Connect ChatBots
- *
- * Class Wechaty
- *
- * Licenst: ISC
- * https://github.com/zixia/wechaty
- *
- */
 import { EventEmitter } from 'events'
 import * as fs          from 'fs'
 import * as path        from 'path'
@@ -48,15 +37,44 @@ export type WechatyEventName = 'error'
                               | 'scan'
                               | 'EVENT_PARAM_ERROR'
 
+/**
+ *
+ * Wechaty: Wechat for ChatBots.
+ * Connect ChatBots
+ *
+ * Class Wechaty
+ *
+ * Licenst: ISC
+ * https://github.com/zixia/wechaty
+ *
+ */
 export class Wechaty extends EventEmitter implements Sayable {
+  /**
+   * singleton _instance
+   */
   private static _instance: Wechaty
 
+  /**
+   * the puppet
+   */
   public puppet: Puppet | null
 
+  /**
+   * the state
+   */
   private state = new StateMonitor<'standby', 'ready'>('Wechaty', 'standby')
+  /**
+   * the npmVersion
+   */
   private npmVersion: string = require('../package.json').version
+  /**
+   * the uuid
+   */
   public uuid:        string
 
+  /**
+   *
+   */
   public static instance(setting?: PuppetSetting) {
     if (setting && this._instance) {
       throw new Error('there has already a instance. no params will be allowed any more')
@@ -67,6 +85,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return this._instance
   }
 
+  /**
+   *
+   */
   private constructor(private setting: PuppetSetting = {}) {
     super()
     log.verbose('Wechaty', 'contructor()')
@@ -86,9 +107,23 @@ export class Wechaty extends EventEmitter implements Sayable {
     this.uuid = UtilLib.guid()
   }
 
+  /**
+   *
+   */
   public toString() { return 'Class Wechaty(' + this.setting.puppet + ')'}
 
-  public version(forceNpm = false) {
+  /**
+   * Return version of Wechaty
+   * @param {boolean} [forceNpm=false] if set to true, will only return the version in package.json.
+   *                            otherwise will return git commit hash if .git exists.
+   * @returns {string} version number
+   * @example
+   *  console.log(Wechaty.instance().version())
+   *  // #git[af39df]
+   *  console.log(Wechaty.instance().version(true))
+   *  // 0.7.9
+   */
+  public version(forceNpm = false): string {
     // TODO: use  git rev-parse HEAD  ?
     const dotGitPath  = path.join(__dirname, '..', '.git') // only for ts-node, not for dist
     const gitLogCmd   = 'git'
@@ -122,6 +157,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return this.npmVersion
   }
 
+  /**
+   * @todo document me
+   */
   public user(): Contact {
     if (!this.puppet || !this.puppet.user) {
       throw new Error('no user')
@@ -129,6 +167,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return this.puppet.user
   }
 
+  /**
+   *
+   */
   public async reset(reason?: string): Promise<void> {
     log.verbose('Wechaty', 'reset() because %s', reason)
     if (!this.puppet) {
@@ -138,6 +179,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return
   }
 
+  /**
+   * @todo document me
+   */
   public async init(): Promise<void> {
     log.info('Wechaty', 'v%s initializing...' , this.version())
     log.verbose('Wechaty', 'puppet: %s'       , this.setting.puppet)
@@ -165,17 +209,55 @@ export class Wechaty extends EventEmitter implements Sayable {
   }
 
   // public on(event: WechatyEventName, listener: Function): this
+  /**
+   * @param {string} [event='error'] the `error` event
+   * @param {Function} listener (error) => void callback function
+   * @return {Wechaty} this for chain
+   */
   public on(event: 'error'      , listener: (this: Wechaty, error: Error) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'friend'     , listener: (this: Wechaty, friend: Contact, request?: FriendRequest) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'heartbeat'  , listener: (this: Wechaty, data: any) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'logout'     , listener: (this: Wechaty, user: Contact) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'login'      , listener: (this: Wechaty, user: Contact) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'message'    , listener: (this: Wechaty, message: Message) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'room-join'  , listener: (this: Wechaty, room: Room, inviteeList: Contact[],  inviter: Contact) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'room-leave' , listener: (this: Wechaty, room: Room, leaverList: Contact[]) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'room-topic' , listener: (this: Wechaty, room: Room, topic: string, oldTopic: string, changer: Contact) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'scan'       , listener: (this: Wechaty, url: string, code: number) => void): this
+  /**
+   * @todo document me
+   */
   public on(event: 'EVENT_PARAM_ERROR', listener: () => void): this
+  /**
+   * @todo document me
+   */
 
   public on(event: WechatyEventName, listener: Function): this {
     log.verbose('Wechaty', 'addListener(%s, %s)', event, typeof listener)
@@ -197,6 +279,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return this
   }
 
+  /**
+   * @todo document me
+   */
   public async initPuppet(): Promise<Puppet> {
     let puppet: Puppet
 
@@ -255,6 +340,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return puppet
   }
 
+  /**
+   * @todo document me
+   */
   public async quit(): Promise<void> {
     log.verbose('Wechaty', 'quit()')
     this.state.current('standby', false)
@@ -277,6 +365,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return
   }
 
+  /**
+   * @todo document me
+   */
   public async logout(): Promise<void>  {
     if (!this.puppet) {
       throw new Error('no puppet')
@@ -299,6 +390,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return this.puppet.self()
   }
 
+  /**
+   * @todo document me
+   */
   public async send(message: Message): Promise<void> {
     if (!this.puppet) {
       throw new Error('no puppet')
@@ -311,6 +405,9 @@ export class Wechaty extends EventEmitter implements Sayable {
     return
   }
 
+  /**
+   * @todo document me
+   */
   public async say(content: string): Promise<void> {
     log.verbose('Wechaty', 'say(%s)', content)
 
@@ -321,12 +418,18 @@ export class Wechaty extends EventEmitter implements Sayable {
     return
   }
 
+  /**
+   * @todo document me
+   */
   public async sleep(millisecond: number): Promise<void> {
     await new Promise(resolve => {
       setTimeout(resolve, millisecond)
     })
   }
 
+  /**
+   * @todo document me
+   */
   public ding() {
     if (!this.puppet) {
       return Promise.reject(new Error('wechaty cant ding coz no puppet'))