jsdoc

lakxtxue · Feb 11, 2017 · 5dc52c9 · 5dc52c9
1 parent 48749c8
commit 5dc52c9
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 72 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -13,52 +13,19 @@ https://github.com/zixia/wechaty
 
 * [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)
+        * ~~[.user()](#Wechaty+user) ⇒ <code>Contact</code>~~
         * [.init()](#Wechaty+init)
         * [.on()](#Wechaty+on)
-        * [.initPuppet()](#Wechaty+initPuppet)
         * [.quit()](#Wechaty+quit)
         * [.logout()](#Wechaty+logout)
-        * [.self()](#Wechaty+self)
+        * [.self()](#Wechaty+self) ⇒ <code>Contact</code>
         * [.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>
@@ -80,16 +47,14 @@ console.log(Wechaty.instance().version())
 ```
 <a name="Wechaty+user"></a>
 
-### wechaty.user()
+### ~~wechaty.user() ⇒ <code>Contact</code>~~
+***Deprecated***
+
 **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()
@@ -106,14 +71,6 @@ console.log(Wechaty.instance().version())
 
 - [ ] 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()
@@ -132,10 +89,11 @@ console.log(Wechaty.instance().version())
 
 <a name="Wechaty+self"></a>
 
-### wechaty.self()
+### wechaty.self() ⇒ <code>Contact</code>
 get current user
 
 **Kind**: instance method of <code>[Wechaty](#Wechaty)</code>  
+**Returns**: <code>Contact</code> - current logined user  
 <a name="Wechaty+send"></a>
 
 ### wechaty.send()
@@ -160,15 +118,9 @@ get current user
 
 - [ ] 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()
+get the singleton instance of Wechaty
+
 **Kind**: static method of <code>[Wechaty](#Wechaty)</code>  
diff --git a/src/wechaty.ts b/src/wechaty.ts
@@ -51,29 +51,34 @@ export type WechatyEventName = 'error'
 export class Wechaty extends EventEmitter implements Sayable {
   /**
    * singleton _instance
+   * @private
    */
   private static _instance: Wechaty
 
   /**
    * the puppet
+   * @private
    */
   public puppet: Puppet | null
 
   /**
    * the state
+   * @private
    */
   private state = new StateMonitor<'standby', 'ready'>('Wechaty', 'standby')
   /**
    * the npmVersion
+   * @private
    */
   private npmVersion: string = require('../package.json').version
   /**
    * the uuid
+   * @private
    */
   public uuid:        string
 
   /**
-   *
+   * get the singleton instance of Wechaty
    */
   public static instance(setting?: PuppetSetting) {
     if (setting && this._instance) {
@@ -86,7 +91,7 @@ export class Wechaty extends EventEmitter implements Sayable {
   }
 
   /**
-   *
+   * @private
    */
   private constructor(private setting: PuppetSetting = {}) {
     super()
@@ -108,13 +113,13 @@ export class Wechaty extends EventEmitter implements Sayable {
   }
 
   /**
-   *
+   * @private
    */
   public toString() { return 'Class Wechaty(' + this.setting.puppet + ')'}
 
   /**
    * Return version of Wechaty
-   * @param {boolean} [forceNpm=false] if set to true, will only return the version in package.json.
+   * @param [forceNpm=false] {boolean} 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
@@ -160,16 +165,19 @@ export class Wechaty extends EventEmitter implements Sayable {
   /**
    * @todo document me
    * @returns {Contact}
+   * @deprecated
    */
   public user(): Contact {
+    log.warn('Wechaty', 'user() DEPRECATED. use self() instead.')
+
     if (!this.puppet || !this.puppet.user) {
       throw new Error('no user')
     }
     return this.puppet.user
   }
 
   /**
-   *
+   * @private
    */
   public async reset(reason?: string): Promise<void> {
     log.verbose('Wechaty', 'reset() because %s', reason)
@@ -211,9 +219,10 @@ 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
+   * @listens Wechaty#error
+   * @param [event='error'] {string}    the `error` event
+   * @param listener        {Function}  listener (error) => void callback function
+   * @return                {Wechaty}   this for chain
    */
   public on(event: 'error'      , listener: (this: Wechaty, error: Error) => void): this
   /**
@@ -282,6 +291,7 @@ export class Wechaty extends EventEmitter implements Sayable {
 
   /**
    * @todo document me
+   * @private
    */
   public async initPuppet(): Promise<Puppet> {
     let puppet: Puppet
@@ -323,13 +333,6 @@ export class Wechaty extends EventEmitter implements Sayable {
         this.emit.apply(this, [e, ...args])
       })
     })
-    /**
-     * TODO: support more events:
-     * 2. send
-     * 3. reply
-     * 4. quit
-     * 5. ...
-     */
 
     // set puppet before init, because we need this.puppet if we quit() before init() finish
     this.puppet = <Puppet>puppet // force to use base class Puppet interface for better encapsolation
@@ -383,6 +386,7 @@ export class Wechaty extends EventEmitter implements Sayable {
 
   /**
    * get current user
+   * @returns {Contact} current logined user
    */
   public self(): Contact {
     if (!this.puppet) {
@@ -430,6 +434,7 @@ export class Wechaty extends EventEmitter implements Sayable {
 
   /**
    * @todo document me
+   * @private
    */
   public ding() {
     if (!this.puppet) {