Add JsDoc for Class Contact (#321)

* testDoc

* test contact

* text contact

* add test

* add contact docs

* revise Gender type

* modify Gender

* done as requested

* modify contactAll description

* delete @memberOf

* add all method example

* rm docs

* recover docs

* done as requested

src/contact.ts

@@ -40,6 +40,10 @@ export type ContactRawObj = {
   stranger:     string, // assign by injectio.js
 }
 
+/**
+ * Enum for Gender values.
+ * @enum {number}
+ */
 export enum Gender {
   Unknown = 0,
   Male    = 1,
@@ -55,9 +59,8 @@ export type ContactQueryFilter = {
 
 /**
  * Class Contact
- * blabla...
- * **IMPORTANT**
  *
+ * `Contact` is `Sayable`
  */
 export class Contact implements Sayable {
   private static pool = new Map<string, Contact>()
@@ -107,20 +110,109 @@ export class Contact implements Sayable {
     }
   }
 
-  public weixin()   { return this.obj && this.obj.weixin || '' }
+  /**
+   * Get the weixin number from a contact
+   * Sometimes cannot get weixin number due to weixin security mechanism, not recommend.
+   * @returns {string | null}
+   *
+   * @example
+   * ```ts
+   * const weixin = contact.weixin()
+   * ```
+   */
+  public weixin()   { return this.obj && this.obj.weixin || null }
+
+  /**
+   * Get the name from a contact
+   *
+   * @returns {string}
+   *
+   * @example
+   * ```ts
+   * const name = contact.name()
+   * ```
+   */
   public name()     { return UtilLib.plainText(this.obj && this.obj.name || '') }
-  public stranger() { return this.obj && this.obj.stranger }
-  public star()     { return this.obj && this.obj.star }
+
+  /**
+   * Check if contact is stranger
+   *
+   * @returns {boolean | null} True for not friend of the bot, False for friend of the bot, null for cannot get the info.
+   *
+   * @example
+   * ```ts
+   * const isStranger = contact.stranger()
+   * ```
+   */
+  public stranger(): boolean|null {
+    if (!this.obj) return null
+    return this.obj.stranger
+  }
+
+  /**
+   * Check if the contact is star contact.
+   *
+   * @returns {boolean} True for star friend, False for no star friend, null for cannot get the info.
+   *
+   * @example
+   * ```ts
+   * const isStar = contact.star()
+   * ```
+   */
+  public star(): boolean|null {
+    if (!this.obj) return null
+    return this.obj.star
+  }
+
   /**
    * Contact gender
+   *
    * @returns Gender.Male(2) | Gender.Female(1) | Gender.Unknown(0)
+   *
+   * @example
+   * ```ts
+   * const gender = contact.gender()
+   * ```
+   */
+  public gender(): Gender   { return this.obj ? this.obj.sex : Gender.Unknown }
+
+  /**
+   * Get the region 'province' from a contact
+   *
+   * @returns {string | undefined}
+   *
+   * @example
+   * ```ts
+   * const province = contact.province()
+   * ```
    */
-  public gender()   { return this.obj ? this.obj.sex : Gender.Unknown }
   public province() { return this.obj && this.obj.province }
+
+  /**
+   * Get the region 'city' from a contact
+   *
+   * @returns {string | undefined}
+   *
+   * @example
+   * ```ts
+   * const city = contact.city()
+   * ```
+   */
   public city()     { return this.obj && this.obj.city }
 
   /**
    * Get avatar picture file stream
+   *
+   * @returns {Promise<NodeJS.ReadableStream>}
+   *
+   * @example
+   * ```ts
+   * const avatarFileName = contact.name() + `.jpg`
+   * const avatarReadStream = await contact.avatar()
+   * const avatarWriteStream = createWriteStream(avatarFileName)
+   * avatarReadStream.pipe(avatarWriteStream)
+   * log.info('Bot', 'Contact: %s: %s with avatar file: %s', contact.weixin(), contact.name(), avatarFileName)
+   * ```
    */
   public async avatar(): Promise<NodeJS.ReadableStream> {
     log.verbose('Contact', 'avatar()')
@@ -153,6 +245,16 @@ export class Contact implements Sayable {
   //   return this.reload()
   // }
 
+  /**
+   * Force reload data for Contact
+   *
+   * @returns {Promise<this>}
+   *
+   * @example
+   * ```ts
+   * await contact.refresh()
+   * ```
+   */
   public async refresh(): Promise<this> {
     if (this.isReady()) {
       this.dirtyObj = this.obj
@@ -203,11 +305,22 @@ export class Contact implements Sayable {
     console.error('======= dump raw contact =======')
     Object.keys(this.rawObj).forEach(k => console.error(`${k}: ${this.rawObj[k]}`))
   }
+
   public dump()    {
     console.error('======= dump contact =======')
     Object.keys(this.obj).forEach(k => console.error(`${k}: ${this.obj && this.obj[k]}`))
   }
 
+  /**
+   * Check if contact is self
+   *
+   * @returns {boolean} True for contact is self, False for contact is others
+   *
+   * @example
+   * ```ts
+   * const isSelf = contact.self()
+   * ```
+   */
   public self(): boolean {
     const userId = Config.puppetInstance()
                           .userId
@@ -223,6 +336,26 @@ export class Contact implements Sayable {
 
   /**
    * find contact by `name` or `alias`
+   *
+   * If use Contact.findAll() get the contact list of the bot.
+   *
+   * #### definition
+   * - `name` the name-string set by user-self, should be called name
+   * - `alias` the name-string set by bot for others, should be called alias
+   *
+   * @static
+   * @param {ContactQueryFilter} [queryArg]
+   * @returns {Promise<Contact[]>}
+   *
+   * @example
+   * ```ts
+   * // get the contact list of the bot
+   * const contactList = await Contact.findAll()
+   * // find allof the contacts whose name is 'ruirui'
+   * const contactList = await Contact.findAll({name: 'ruirui'})
+   * // find allof the contacts whose alias is 'lijiarui'
+   * const contactList = await Contact.findAll({alias: 'lijiarui'})
+   * ```
    */
   public static async findAll(queryArg?: ContactQueryFilter): Promise<Contact[]> {
     let query: ContactQueryFilter
@@ -292,16 +425,52 @@ export class Contact implements Sayable {
   }
 
   /**
-   * get the alias for contact
+   * Get the alias for contact
+   *
+   * @returns {(string | null)}
+   *
+   * @example
+   * ```ts
+   * const alias = contact.alias()
+   * ```
    */
   public alias(): string | null
+
   /**
    * set the alias for contact
-   * @return {Promise<boolean>} A promise to the result. true for success, false for failure
+   *
+   * tests show it will failed if set alias too frequently(60 times in one minute).
+   *
+   * @param {string} newAlias
+   * @returns {Promise<boolean>} A promise to the result. true for success, false for failure
+   *
+   * @example
+   * ```ts
+   * const ret = await contact.remark('lijiarui')
+   * if (ret) {
+   *   console.log(`change ${contact.name()}'s alias successfully!`)
+   * } else {
+   *   console.error('failed to change ${contact.name()}'s alias!')
+   * }
+   * ```
    */
   public alias(newAlias: string): Promise<boolean>
+
   /**
-   * delete the alias for a contact
+   * Delete the alias for a contact
+   *
+   * @param {null} empty
+   * @returns {Promise<boolean>}
+   *
+   * @example
+   * ```ts
+   * const ret = await contact.remark(null)
+   * if (ret) {
+   *   console.log('ok!')
+   * } else {
+   *   console.error('fail!')
+   * }
+   * ```
    */
   public alias(empty: null): Promise<boolean>
 
@@ -349,8 +518,16 @@ export class Contact implements Sayable {
 
   /**
    * try to find a contact by filter: {name: string | RegExp} / {alias: string | RegExp}
+   * @description Find contact by name or alias, if the result more than one, return the first one.
+   * @static
    * @param {ContactQueryFilter} query
-   * @returns {Promise<Contact | null>} If can find the contact, return Contact, or return null
+   * @returns {(Promise<Contact | null>)} If can find the contact, return Contact, or return null
+   *
+   * @example
+   * ``` ts
+   * const contactFindByName = await Contact.find({ name:"ruirui"} )
+   * const contactFindByAlias = await Contact.find({ alias:"lijiarui"} )
+   * ```
    */
   public static async find(query: ContactQueryFilter): Promise<Contact | null> {
     log.verbose('Contact', 'find(%s)', JSON.stringify(query))
@@ -366,6 +543,19 @@ export class Contact implements Sayable {
     return contactList[0]
   }
 
+  /**
+   * Load data for Contact by id
+   *
+   * @static
+   * @param {string} id
+   * @returns {Contact}
+   *
+   * @example
+   * ``` ts
+   * // fake: contactId = @0bb3e4dd746fdbd4a80546aef66f4085
+   * const contact = Contact.load('@0bb3e4dd746fdbd4a80546aef66f4085')
+   * ```
+   */
   public static load(id: string): Contact {
     if (!id || typeof id !== 'string') {
       throw new Error('Contact.load(): id not found')
@@ -377,6 +567,17 @@ export class Contact implements Sayable {
     return Contact.pool[id]
   }
 
+  /**
+   * Say `content` to Contact
+   *
+   * @param {string} content
+   * @returns {Promise<void>}
+   *
+   * @example
+   * ``` ts
+   * await contact.say('welcome to wechaty!')
+   * ```
+   */
   public async say(content: string): Promise<void> {
     log.verbose('Contact', 'say(%s)', content)