From b3a876d305a8012d5668e1eb313a021d2a062830 Mon Sep 17 00:00:00 2001 From: lijiarui Date: Mon, 13 Mar 2017 12:29:38 +0800 Subject: [PATCH] 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 | 221 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 211 insertions(+), 10 deletions(-) diff --git a/src/contact.ts b/src/contact.ts index 8a9214a98..1a1cddab3 100644 --- a/src/contact.ts +++ b/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() @@ -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} + * + * @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 { log.verbose('Contact', 'avatar()') @@ -153,6 +245,16 @@ export class Contact implements Sayable { // return this.reload() // } + /** + * Force reload data for Contact + * + * @returns {Promise} + * + * @example + * ```ts + * await contact.refresh() + * ``` + */ public async refresh(): Promise { 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} + * + * @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 { 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} 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} 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 + /** - * delete the alias for a contact + * Delete the alias for a contact + * + * @param {null} empty + * @returns {Promise} + * + * @example + * ```ts + * const ret = await contact.remark(null) + * if (ret) { + * console.log('ok!') + * } else { + * console.error('fail!') + * } + * ``` */ public alias(empty: null): Promise @@ -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} If can find the contact, return Contact, or return null + * @returns {(Promise)} 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 { 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} + * + * @example + * ``` ts + * await contact.say('welcome to wechaty!') + * ``` + */ public async say(content: string): Promise { log.verbose('Contact', 'say(%s)', content) -- GitLab