Add JsDoc for Class Contact #321

lijiarui · 2017-03-12T10:00:58Z

#73
#252
use JsDoc to generate contact doc here.
Doc: Contact

huan

Good job. Please follow my reviews.

huan · 2017-03-12T14:12:43Z

docs/index.md

+
+**Kind**: global enum  
+**Read only**: true  
+**Export**:   
 <a name="config_1"></a>

 ## config_1


Notice here; there must be someplace mis-documented in the source code.

Please get rid of this.(by modifying code, instead of the auto-generated doc file)

After I modified as you requested, it has changed automatically, maybe it is correct now.

huan · 2017-03-12T14:14:10Z

src/contact.ts

+/**
+ * Enum for Gender values.
+ * @readonly
+ * @export


Could you confirm that @readonly & @export here is necessary?

If so, please explain why.

As my understanding, this is not necessary at here.

You are right, keep it simple, only list the useful thing.

huan · 2017-03-12T14:14:52Z

src/contact.ts

 export enum Gender {
+  /** The Unknown value */


The comments here is not necessary: the code already can explain itself.

Also the following two: Male & Female.

huan · 2017-03-12T15:15:58Z

src/contact.ts

 *
+ * `Contact` is `Sayable`


Please add example to each method.

like:

/** * @example * ```ts * code here * ``` */

I don't think we should add each method, some method like Contact.name(), the code already can explain itself as Gender you said.

I have added method Contact.find() in this commit.

But your suggestion make sense, except method find, I think I should add the following method:

avatar()

say()

What other functions do you think I should add too?

I do not agree. The Document is different to the Code.

Examples can help users to understand easier how to use it rather than reading the API reference.

Now what you think it's obviously but for others are not, that's because you are too familiar with Wechaty.

I think to add examples for all API functions is necessary, but I'll leave this decision to you.

Please add examples to the APIs which you think is needed, leave it without example as you like.

You are right, maybe I'm too familiar with Wechaty, so I add examples for all API functions.
And I added all the methods examples

huan · 2017-03-12T15:16:37Z

src/contact.ts

  public name()     { return UtilLib.plainText(this.obj && this.obj.name || '') }
+
+  /**
+   * Check if contact is strange


is stranger.

huan · 2017-03-12T15:18:41Z

src/contact.ts

+   * @static
+   * @param {ContactQueryFilter} [queryArg]
+   * @returns {Promise<Contact[]>}
+   * @description If use Contact.findAll() get the contact list of the bot.


Put @description at the beginning of the comment block.

Because the comments at the beginning of the comment block is default to be @description.

huan · 2017-03-12T15:19:50Z

src/contact.ts

+   *
+   * @returns {(string | null)}
+   *
+   * @memberOf Contact


@memberOf is not needed in ES6/Typescript.

Because the JsDoc is already known it is member of the class.

So your suggestion is to delete all @memberOf ?

Yes.

Unless you have a reason for keeping it.

huan · 2017-03-12T15:21:38Z

src/contact.ts

+   * ```
+   * const contactFindByName = await Contact.find({ name:"ContactName"} )
+   * const contactFindByAlias = await Contact.find({ alias:"ContactAlias"} )
+   * ```


specify the type of the example.

here should be:

```ts

… 'master' of https://github.com/wechaty/wechaty into testDoc

huan

You did not follow my last reviews.

huan · 2017-03-13T02:31:40Z

docs/index.md

@@ -25,9 +25,8 @@ Wechaty.instance() // Singleton
 <p>Add/Del/Topic: <a href="https://github.com/wechaty/wechaty/issues/32">https://github.com/wechaty/wechaty/issues/32</a></p>
 </dd>
 <dt><a href="#Contact">Contact</a></dt>
-<dd><p>Class Contact


Do not commit the new docs/index.md in this PR.

Because this is not necessary.

Please only commit the code file.

I won't commit docs/index.md in this PR any more.

huan · 2017-03-13T02:32:38Z

src/contact.ts

+   *
+   * @returns {string | ''}
+   *
+   * @memberOf Contact


I didn't commit yet after your comment...

huan · 2017-03-13T02:33:10Z

src/contact.ts

+   *
+   * @returns {string | ''}
+   *
+   * @memberOf Contact


@memberof is not necessary as we discussed.

lijiarui · 2017-03-13T03:14:40Z

@zixia
done all of your request.

@memberof
removed all @memberOf
example
You are right, maybe I'm too familiar with Wechaty, so I add examples for all API functions.

huan · 2017-03-13T03:17:24Z

No, you are not done.

Please mark all my reviews as resolved after you confirmed it is resolved.

I noticed that there has some reviews you did not reply/react.

lijiarui · 2017-03-13T03:20:35Z

How about this time?

huan · 2017-03-13T03:22:13Z

I don't know.

Please tell me you are done after you are done.

lijiarui · 2017-03-13T03:24:07Z

done

lijiarui · 2017-03-13T03:28:22Z

I'm sorry....

I thought I used wrong git command...
I should use git rm –cached instead of git rm to delete index instead of delete both index and the file.

But I thought your bot can generate the docs automatically.

huan · 2017-03-13T03:28:39Z

No, you are not done.

you leave one un-resolved review.
you should not commit the file docs/index.md. this time you still commit it, with worse behaviour: deleted it. I need your PR only include one file modification instead of two.

lijiarui · 2017-03-13T03:33:39Z

done

huan · 2017-03-13T03:36:39Z

Not yet.

lijiarui · 2017-03-13T03:57:48Z

I'm not sure which haven't done....

1.you leave one un-resolved review.
2.you should not commit the file docs/index.md. this time you still commit it, with worse behaviour: deleted it. I need your PR only include one file modification instead of two.

I have replyed your example review and added all methods examples in c367b99
I have recovered file I deleted in 1e16c0b

So could you tell me more?
Thanks.

huan

Please fulfill all the return type for functions, and make sure the function body is returning the right type.

huan · 2017-03-13T03:55:42Z

src/contact.ts

+  /**
+   * Get the weixin number from a contact
+   * Sometimes cannot get weixin number due to weixin security mechanism, not recommend.
+   * @returns {string | ''}


@returns {string}

or {string|null} is better, for null is standing for we can not get the wexin id.

huan · 2017-03-13T03:56:51Z

src/contact.ts

+   * ```ts
+   * const weixin = contact.weixin()
+   * ```
+   */
  public weixin()   { return this.obj && this.obj.weixin || '' }


public weixin(): string
or
public wexin(): string | null

huan · 2017-03-13T03:57:02Z

src/contact.ts

+  /**
+   * Get the name from a contact
+   *
+   * @returns {string | ''}


@returns {string}

huan · 2017-03-13T03:57:33Z

src/contact.ts

+   * ```ts
+   * const isStranger = contact.stranger()
+   * ```
+   */
  public stranger() { return this.obj && this.obj.stranger }


public stranger(): boolean

and make sure the function is return a type of boolean

huan · 2017-03-13T03:57:54Z

src/contact.ts

+   * ```ts
+   * const isStar = contact.star()
+   * ```
+   */
  public star()     { return this.obj && this.obj.star }


public star(): boolean

and make sure the function is return a type of boolean

huan · 2017-03-13T03:58:10Z

src/contact.ts

+   * @example
+   * ```ts
+   * const gender = contact.gender()
+   * ```
   */
  public gender()   { return this.obj ? this.obj.sex : Gender.Unknown }


public gender(): Gender

huan · 2017-03-13T04:01:59Z

Last time you leave this review unresolved:

lijiarui · 2017-03-13T04:16:24Z

done fulfill all the return type for functions...
But I'm not sure whether I have resolved the example review...
Could you tell me?
Thanks

huan · 2017-03-13T04:28:26Z

You still leave one review unresolved.

But it's ok, I'll merge this PR now.

huan · 2017-03-13T04:29:31Z

BTW: there's a bug that causing the unit test failed, it seems related to the PR from you recently.

Please have a look when you have time. Thanks.

lijiarui · 2017-03-13T04:44:00Z

Could you tell me how to resolve the review?
Thanks

huan · 2017-03-13T04:49:00Z

I do not know because I can not see your account.

lijiarui added 7 commits March 11, 2017 18:50

testDoc

d7e1e2d

test contact

4858f60

text contact

89c6fd4

add test

485d493

add contact docs

6870c61

revise Gender type

2a7adce

modify Gender

7a117a9

lijiarui mentioned this pull request Mar 12, 2017

[doc] Contribute to the doc editing[ jsdoc / jsdoc2md / typedoc ] #252

Closed

huan requested changes Mar 12, 2017

View reviewed changes

lijiarui added 3 commits March 13, 2017 09:52

Merge branch 'testDoc' of https://github.com/lijiarui/wechaty; branch…

e86d3d0

… 'master' of https://github.com/wechaty/wechaty into testDoc

done as requested

d57b684

modify contactAll description

de11d46

huan requested changes Mar 13, 2017

View reviewed changes

lijiarui added 2 commits March 13, 2017 10:44

delete @memberof

eae8c05

add all method example

c367b99

rm docs

bfb84b6

recover docs

1e16c0b

huan requested changes Mar 13, 2017

View reviewed changes

done as requested

0d8dfe6

huan merged commit b3a876d into wechaty:master Mar 13, 2017

lijiarui deleted the testDoc branch March 27, 2017 12:41

Add JsDoc for Class Contact #321

Add JsDoc for Class Contact #321

Conversation

lijiarui commented Mar 12, 2017

huan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huan Mar 13, 2017 • edited Loading

Choose a reason for hiding this comment

lijiarui Mar 13, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lijiarui commented Mar 13, 2017 • edited Loading

huan commented Mar 13, 2017

lijiarui commented Mar 13, 2017

huan commented Mar 13, 2017

lijiarui commented Mar 13, 2017

lijiarui commented Mar 13, 2017 • edited Loading

huan commented Mar 13, 2017 • edited Loading

lijiarui commented Mar 13, 2017

huan commented Mar 13, 2017

lijiarui commented Mar 13, 2017 • edited Loading

huan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huan commented Mar 13, 2017

lijiarui commented Mar 13, 2017

huan commented Mar 13, 2017

huan commented Mar 13, 2017

lijiarui commented Mar 13, 2017

huan commented Mar 13, 2017

huan Mar 13, 2017 •

edited

Loading

lijiarui Mar 13, 2017 •

edited

Loading

lijiarui commented Mar 13, 2017 •

edited

Loading

lijiarui commented Mar 13, 2017 •

edited

Loading

huan commented Mar 13, 2017 •

edited

Loading

lijiarui commented Mar 13, 2017 •

edited

Loading