Merge branch 'master' of github.com:Chatie/wechaty

scripts/generate-docs.sh

@@ -10,5 +10,5 @@ else
   echo "Generating docs ..."
   npm run dist
   echo -e '# Wechaty v'$(jq -r .version package.json)' Documentation\n\n* <https://blog.chatie.io>\n\n' > docs/index.md
-  jsdoc2md dist/src/wechaty.js dist/src/user/{room,contact,friendship,message}.js >> docs/index.md
+  jsdoc2md dist/src/wechaty.js dist/src/user/{room,contact,contact-self,friendship,message}.js >> docs/index.md
 fi

src/user/contact-self.ts

@@ -27,6 +27,17 @@ import {
   Contact,
 }           from './contact'
 
+/**
+ * Bot itself will be encapsulated as a ContactSelf.
+ *
+ * > Tips: this class is extends Contact
+ * @example
+ * const bot = new Wechaty()
+ * await bot.start()
+ * bot.on('login', (user: ContactSelf) => {
+ *   console.log(`user ${user} login`)
+ * })
+ */
 export class ContactSelf extends Contact {
   constructor (
     id: string,
@@ -37,6 +48,33 @@ export class ContactSelf extends Contact {
   public async avatar ()              : Promise<FileBox>
   public async avatar (file: FileBox) : Promise<void>
 
+  /**
+   * GET / SET bot avatar
+   *
+   * @param {FileBox} [file]
+   * @returns {(Promise<void | FileBox>)}
+   *
+   * @example <caption> GET the avatar for bot, return {Promise<FileBox>}</caption>
+   * // Save avatar to local file like `1-name.jpg`
+   *
+   * bot.on('login', (user: ContactSelf) => {
+   *   console.log(`user ${user} login`)
+   *   const file = await user.avatar()
+   *   const name = file.name
+   *   await file.toFile(name, true)
+   *   console.log(`Save bot avatar: ${contact.name()} with avatar file: ${name}`)
+   * })
+   *
+   * @example <caption>SET the avatar for a bot</caption>
+   * import { FileBox }  from 'file-box'
+   * bot.on('login', (user: ContactSelf) => {
+   *   console.log(`user ${user} login`)
+   *   const fileBox = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
+   *   await user.avatar(fileBox)
+   *   console.log(`Change bot avatar successfully!`)
+   * })
+   *
+   */
   public async avatar (file?: FileBox): Promise<void | FileBox> {
     log.verbose('Contact', 'avatar(%s)', file ? file.name : '')
 
@@ -52,6 +90,20 @@ export class ContactSelf extends Contact {
     await this.puppet.contactAvatar(this.id, file)
   }
 
+  /**
+   * Get bot qrcode
+   *
+   * @returns {Promise<string>}
+   *
+   * @example
+   * import { generate } from 'qrcode-terminal'
+   * bot.on('login', (user: ContactSelf) => {
+   *   console.log(`user ${user} login`)
+   *   const qrcode = await user.qrcode()
+   *   console.log(`Following is the bot qrcode!`)
+   *   generate(qrcode, { small: true })
+   * })
+   */
   public async qrcode (): Promise<string> {
     log.verbose('Contact', 'qrcode()')
 

src/user/contact.ts

@@ -341,7 +341,7 @@ export class Contact extends Accessory implements Sayable {
    *
    * import { FileBox }  from 'file-box'
    * const fileBox1 = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
-   * const fileBox2 = FileBox.fromLocal('/tmp/text.txt')
+   * const fileBox2 = FileBox.fromFile('/tmp/text.txt')
    * await contact.say(fileBox1)
    * await contact.say(fileBox2)
    *