New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
ax4 opened this Issue Feb 14, 2017 · 13 comments

Comments

4 participants
@ax4
Member

ax4 commented Feb 14, 2017

Hi,

I find the API doc need:

  • some minor fix (such as the different naming Message Class & Class Room)
  • improvement on the formatting, e.g. the level setting of each title
  • maybe, add an index for better guiding

I am volunteering to contribute to doc. I was wondering what should I do? Thanks!

@ax4 ax4 changed the title from How can I make contribute to the doc writing? to How can I make contribute to the doc editing? Feb 14, 2017

@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia Feb 15, 2017

Member

Hi @ax4 ,

Welcome!

An useful FrameWork with good document will help the community save lots of times. Wechaty is an useful ChatBot FrameWork, it need to be well ducumented.

We have a plan to re-document Wechaty, you can join us. Please see #73 .

Thank you very much for your volunteering!

Member

zixia commented Feb 15, 2017

Hi @ax4 ,

Welcome!

An useful FrameWork with good document will help the community save lots of times. Wechaty is an useful ChatBot FrameWork, it need to be well ducumented.

We have a plan to re-document Wechaty, you can join us. Please see #73 .

Thank you very much for your volunteering!

@lijiarui

This comment has been minimized.

Show comment
Hide comment
@lijiarui

lijiarui Feb 16, 2017

Member

@ax4 We are trying to just give outlined api in API doc, could you give an outline suggestion here?

Member

lijiarui commented Feb 16, 2017

@ax4 We are trying to just give outlined api in API doc, could you give an outline suggestion here?

@ax4

This comment has been minimized.

Show comment
Hide comment
@ax4

ax4 Feb 17, 2017

Member

@lijiarui Hi, good to hear that!! I think, a good UserGuide & API doc should be based on User's most demand. And it will gradually guide him/her from "Learn the awesome features of Wechaty" -> "See more advanced functions" -> "Reach the boundary? Help us develop Wechaty". So I would suggest the outline as below:

  • Introduction to Wechaty
    • HelloWorld
    • Save my login status (profile)
  • Basic Events of Wechaty
    • scan
    • login
    • logout
    • message
    • error
    • friend
    • room-join
    • room-leave
    • room-topic
  • Reply a Message to Contact / Room
    • Reply to Contact
    • Reply to Room
  • Search for Contact / Room (Query Type) and Say "Hello, I am a bot"
    • Contact Query Type
    • Room Query Type
  • API Details of Class
    • Wechaty Class
      • Wechaty.instance(profile:string): Wechaty
      • Wechaty.init(): Wechaty
      • Wechaty.send(message: Message): Wechaty
      • Wechaty.say(content: string)
    • Message Class
      • Message.from(contact?: Contact|string): Contact
      • Message.to(contact?: Contact|string): Contact | void
      • Message.content(content?: string): string
      • Message.room(room?: Room|string): Room | void
      • Message.type(): MsgType
      • Message.typeApp(): AppMsgType
      • Message.say(content: string): Promise
      • Message.self(message: Message): boolean
      • Message.id: string
      • Message.filename():string
    • Contact Class
      • Contact.id: string
      • Contact.name(): string | ''
      • Contact.city(): string | undefined
      • Contact.province(): string | undefined
      • Contact.gender(): Gender | undefine
      • Contact.avatar():
      • Contact.alias(): string | null
      • Contact.alias(alias: string): Promise
      • Contact.weixin(): string | ''
      • Contact.star(): boolean
      • Contact.refresh(): Promise
      • Contact.self(): boolean
      • Contact.stranger(): boolean
      • Contact.say(content: string): Promise
      • Contact Query Type
    • Room Class
      • Room.say(content: string, replyTo: Contact|Contact[]): Promise
      • Room.refresh(): Promise
      • Room Events
      • Room Query Type
      • Room.add(contact: Contact): Promise
      • Room.del(contact: Contact): void
      • Room.topic(newTopic?: string): string | void
      • Room.alias (contact: Contact): string
      • Room.has(contact Contact): boolean
      • Room.owner(): Contact | null
      • Room.member(name: string): Contact | null
      • Room.member({alias: string}): Contact|null
      • Room.member({name: string}): Contact|null
      • Room.memberList(): Contact[]
    • FriendRequest Class
      • FriendRequest.hello: string
      • FriendRequest.accept(): Promise
      • FriendRequest.send(contact: Contact, hello: string): Promise
Member

ax4 commented Feb 17, 2017

@lijiarui Hi, good to hear that!! I think, a good UserGuide & API doc should be based on User's most demand. And it will gradually guide him/her from "Learn the awesome features of Wechaty" -> "See more advanced functions" -> "Reach the boundary? Help us develop Wechaty". So I would suggest the outline as below:

  • Introduction to Wechaty
    • HelloWorld
    • Save my login status (profile)
  • Basic Events of Wechaty
    • scan
    • login
    • logout
    • message
    • error
    • friend
    • room-join
    • room-leave
    • room-topic
  • Reply a Message to Contact / Room
    • Reply to Contact
    • Reply to Room
  • Search for Contact / Room (Query Type) and Say "Hello, I am a bot"
    • Contact Query Type
    • Room Query Type
  • API Details of Class
    • Wechaty Class
      • Wechaty.instance(profile:string): Wechaty
      • Wechaty.init(): Wechaty
      • Wechaty.send(message: Message): Wechaty
      • Wechaty.say(content: string)
    • Message Class
      • Message.from(contact?: Contact|string): Contact
      • Message.to(contact?: Contact|string): Contact | void
      • Message.content(content?: string): string
      • Message.room(room?: Room|string): Room | void
      • Message.type(): MsgType
      • Message.typeApp(): AppMsgType
      • Message.say(content: string): Promise
      • Message.self(message: Message): boolean
      • Message.id: string
      • Message.filename():string
    • Contact Class
      • Contact.id: string
      • Contact.name(): string | ''
      • Contact.city(): string | undefined
      • Contact.province(): string | undefined
      • Contact.gender(): Gender | undefine
      • Contact.avatar():
      • Contact.alias(): string | null
      • Contact.alias(alias: string): Promise
      • Contact.weixin(): string | ''
      • Contact.star(): boolean
      • Contact.refresh(): Promise
      • Contact.self(): boolean
      • Contact.stranger(): boolean
      • Contact.say(content: string): Promise
      • Contact Query Type
    • Room Class
      • Room.say(content: string, replyTo: Contact|Contact[]): Promise
      • Room.refresh(): Promise
      • Room Events
      • Room Query Type
      • Room.add(contact: Contact): Promise
      • Room.del(contact: Contact): void
      • Room.topic(newTopic?: string): string | void
      • Room.alias (contact: Contact): string
      • Room.has(contact Contact): boolean
      • Room.owner(): Contact | null
      • Room.member(name: string): Contact | null
      • Room.member({alias: string}): Contact|null
      • Room.member({name: string}): Contact|null
      • Room.memberList(): Contact[]
    • FriendRequest Class
      • FriendRequest.hello: string
      • FriendRequest.accept(): Promise
      • FriendRequest.send(contact: Contact, hello: string): Promise
@lijiarui

This comment has been minimized.

Show comment
Hide comment
@lijiarui

lijiarui Feb 17, 2017

Member

@ax4 Sounds Great!

@zixia How do you think about it?

Member

lijiarui commented Feb 17, 2017

@ax4 Sounds Great!

@zixia How do you think about it?

@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia Feb 17, 2017

Member

Fantastic. It's very clear and effective for introducing Wechaty API.

After we finished the new documents, I'd like to invite @ax4 to write a blog post for Wechaty about the API usage introduction. I believe it will be one of the most useful article of Wechaty for new developers.

Thanks!

Member

zixia commented Feb 17, 2017

Fantastic. It's very clear and effective for introducing Wechaty API.

After we finished the new documents, I'd like to invite @ax4 to write a blog post for Wechaty about the API usage introduction. I believe it will be one of the most useful article of Wechaty for new developers.

Thanks!

@zixia zixia added the enhancement label Feb 17, 2017

@zixia zixia added this to Undocumented Feature in Document Feb 17, 2017

@lijiarui

This comment has been minimized.

Show comment
Hide comment
@lijiarui

lijiarui Mar 12, 2017

Member

@ax4 Sorry for not contacting you in a long time.

We suggest using JsDoc to generate doc automatically where @zixia had said in #73

I have added a contact doc here in New PR to show you the example.

I suggest we can use jsDoc for the following wechaty classes to generate doc here and then use the outline you write in wiki.

Then as you said, we can leading one to see more in detail in the doc.

About wechaty Class, I suggest the following files to add jsDoc:

After you add docs in the codes above, you can run the following code to generate jsdoc and see the changes in wechaty/docs/index.md

npm run doc

Reference

  • jsdoc Introduction
  • jsdoc English document
  • jsdoc Chinese document
  • Document This
    I use vscode as my editor, and use dothis
    "Document This" is a Visual Studio Code extension that automatically generates detailed JSDoc comments for both TypeScript and JavaScript files. You can use Ctrl+Alt+D and again Ctrl+Alt+D to generates documentation for whatever the caret is on or inside of.
Member

lijiarui commented Mar 12, 2017

@ax4 Sorry for not contacting you in a long time.

We suggest using JsDoc to generate doc automatically where @zixia had said in #73

I have added a contact doc here in New PR to show you the example.

I suggest we can use jsDoc for the following wechaty classes to generate doc here and then use the outline you write in wiki.

Then as you said, we can leading one to see more in detail in the doc.

About wechaty Class, I suggest the following files to add jsDoc:

After you add docs in the codes above, you can run the following code to generate jsdoc and see the changes in wechaty/docs/index.md

npm run doc

Reference

  • jsdoc Introduction
  • jsdoc English document
  • jsdoc Chinese document
  • Document This
    I use vscode as my editor, and use dothis
    "Document This" is a Visual Studio Code extension that automatically generates detailed JSDoc comments for both TypeScript and JavaScript files. You can use Ctrl+Alt+D and again Ctrl+Alt+D to generates documentation for whatever the caret is on or inside of.
@lijiarui

This comment has been minimized.

Show comment
Hide comment
@lijiarui

lijiarui Mar 17, 2017

Member

@ax4 hi, how are things going?
I'm glad to help if you have any questions, or you can add my wechat: 13141321843

Member

lijiarui commented Mar 17, 2017

@ax4 hi, how are things going?
I'm glad to help if you have any questions, or you can add my wechat: 13141321843

@ax4

This comment has been minimized.

Show comment
Hide comment
@ax4

ax4 Mar 30, 2017

Member

@lijiarui @zixia Hi, I have found another doc-generator: TypeDoc (http://typedoc.org)

I would recommend TypeDoc rather than jsDoc or jsDoc2md, based on the facts:

  • TypeDoc has better support for TypeScript, than the other two tools
  • TypeDoc give an API document as a HTML site, which is more informative than a single markdown file.
  • It also supports the embedded jsDoc syntax.

Overall, I will vote for TypeDoc.

Reference:
TypeDoc Official
Generating Document for Typescript Project (TypeDoc) by Cloudflare
My PR #375 (closed, just show how TypeDoc looks like)

Member

ax4 commented Mar 30, 2017

@lijiarui @zixia Hi, I have found another doc-generator: TypeDoc (http://typedoc.org)

I would recommend TypeDoc rather than jsDoc or jsDoc2md, based on the facts:

  • TypeDoc has better support for TypeScript, than the other two tools
  • TypeDoc give an API document as a HTML site, which is more informative than a single markdown file.
  • It also supports the embedded jsDoc syntax.

Overall, I will vote for TypeDoc.

Reference:
TypeDoc Official
Generating Document for Typescript Project (TypeDoc) by Cloudflare
My PR #375 (closed, just show how TypeDoc looks like)

@lijiarui

This comment has been minimized.

Show comment
Hide comment
@lijiarui

lijiarui Mar 30, 2017

Member

Glad to hear from you!
Waiting for your new PR ^-^

Member

lijiarui commented Mar 30, 2017

Glad to hear from you!
Waiting for your new PR ^-^

@ax4 ax4 changed the title from How can I make contribute to the doc editing? to How can I make contribute to the doc editing? [ jsdoc / jsdoc2md / typedoc ] Mar 30, 2017

@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia Mar 30, 2017

Member

@ax4 I had read all of the typedoc docs before, including the CloudFlare one.

Typedoc is the first tool I would like to choice at first.But finally I found it does not meet my following two requirements:

  1. Simple and clear: it generate too much information than we needed. It is more like a Microsoft-style.
  2. Generate markdown for better readable version control and GitHub page hosting.

I try to find a tsdoc to md / template plugin but only found some in progress one. (i.e., spatools/ts2jsdoc#4 TypeStrong/typedoc#174 )

That's the reason why I choice tsc + jsdoc at last.

My suggestion is to finish the first version of our jsdoc document with the current tsc + jsdoc flow. After that, we can start to compare other methods.

Member

zixia commented Mar 30, 2017

@ax4 I had read all of the typedoc docs before, including the CloudFlare one.

Typedoc is the first tool I would like to choice at first.But finally I found it does not meet my following two requirements:

  1. Simple and clear: it generate too much information than we needed. It is more like a Microsoft-style.
  2. Generate markdown for better readable version control and GitHub page hosting.

I try to find a tsdoc to md / template plugin but only found some in progress one. (i.e., spatools/ts2jsdoc#4 TypeStrong/typedoc#174 )

That's the reason why I choice tsc + jsdoc at last.

My suggestion is to finish the first version of our jsdoc document with the current tsc + jsdoc flow. After that, we can start to compare other methods.

@zixia zixia changed the title from How can I make contribute to the doc editing? [ jsdoc / jsdoc2md / typedoc ] to [doc] Contribute to the doc editing[ jsdoc / jsdoc2md / typedoc ] Mar 31, 2017

@lijiarui lijiarui assigned lijiarui and unassigned lijiarui and ax4 Jun 21, 2017

@kis87988

This comment has been minimized.

Show comment
Hide comment
@kis87988

kis87988 Jun 26, 2017

Contributor

I will try to contribute about this issue

Contributor

kis87988 commented Jun 26, 2017

I will try to contribute about this issue

@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia Jun 26, 2017

Member

@kis87988 That's awesome, welcome and looking forward to your PR for documents!

Member

zixia commented Jun 26, 2017

@kis87988 That's awesome, welcome and looking forward to your PR for documents!

@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia Aug 26, 2017

Member

Merge to #73

Member

zixia commented Aug 26, 2017

Merge to #73

@zixia zixia closed this Aug 26, 2017

@zixia zixia added the duplicate label Aug 26, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment