Using Jsdoc to sync the doc with the latest code

Posted 2021-04-30 句子互动

点击上方 “句子互动” 关注

In order to sync the doc with the latest code , it’s  best to use jsdoc to describe the  API and use jsdoc-to-markdown to generate markdown format documents to the docs directory.

jsdoc详见：

https://github.com/jsdoc3/jsdoc

 jsdoc-to-markdown详见：

https://github.com/jsdoc2md/jsdoc-to-markdown

Yes, we planned to do this for nearly a year…

Thanks to @Huan, @ax4,@hczhcz, @William, by the end of August, we finally convert all the doc to jsdoc. And I’d like to share some jsdoc experience here.

 Huan,资料详见：https://github.com/zixia

ax4,资料详见：https://github.com/ax4

hczhcz,资料详见：https://github.com/hczhcz

William资料详见：https://github.com/kis87988

We need to document them better, not only the public but also the internal modules and methods.
Finally we decided to use the classic jsdoc to embed document in TypeScript, then generate document to docs/ by jsdoc2md. 
– @Huan said in issue 73 in Nov 2016.

jsdoc详见：

http://usejsdoc.org/

docs/ 详见：

https://github.com/Chatie/wechaty/tree/master/docs

jsdoc2md详见：

https://github.com/jsdoc2md/jsdoc-to-markdown

issue 73详见：

https://github.com/Chatie/wechaty/issues/73

At first, we write the doc in wiki, and it lasts for nearly a year…..

wiki详见：

https://github.com/Chatie/wechaty/wiki

A lot of developers use wiki to learn wechaty, but the wiki’s performance is not good, it cannot update automatically and doesn’t base on user’s most demand.

• 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 
  – In Feb 2017, @ax4 creat an issue and expressed his willingness to contribute the document.

Message Class 详见：

https://github.com/Chatie/wechaty/wiki/API#message-class

Class Room详见：

https://github.com/Chatie/wechaty/wiki/API#class-room

issue详见：

https://github.com/Chatie/wechaty/issues/252

I like @ax4’s idea about the document guide:

• First: Learn the awesome features of Wechaty

• Second: See more advanced functions

• Third: Reach the boundary? Help us develop Wechaty

Thanks for @ax4’s suggestion and we decide to do the doc as soon as possible.

JsDoc && jsdoc2md

JsDoc is an API documentation generator for javascript 

JsDoc详见：http://usejsdoc.org/

jsdoc-to-markdown is a tool to help developers create markdown API document from jsdoc-commented

jsdoc-to-markdown 详见：

https://github.com/jsdoc2md/jsdoc-to-markdown

JsDoc

JSDoc’s purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like modules, namespaces, classes, methods, method parameters, and so on.

JSDoc comments should generally be placed immediately before the code being documented. Each comment must start with a /** sequence in order to be recognized by the JSDoc parser. Comments beginning with /*, /***, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.

The simplest documentation is just a description

/** This is a description of the foo function. */function foo() {}

Reference

• jsdoc Introduction

• jsdoc English document

• jsdoc Chinese document

• Document This 
  I use vscode as my editor, and use Document This “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.

jsdocIntroduction详见：

http://2ality.com/2011/08/jsdoc-intro.html

jsdoc English document详见：

http://usejsdoc.org/

jsdoc Chinese document详见：

http://www.css88.com/doc/jsdoc/

Document This详见：

https://marketplace.visualstudio.com/items?itemName=joelday.docthis

jsdoc2md

Generates markdown API documentation from jsdoc annotated source code. Useful for injecting API docs into project README files.

When you document your code using valid jscode comments and run jsdoc command (e.g. jsdoc2md example.js), then you can get a markdown output easily.

At first, I just write all of jsdoc in the code and link wechaty/docs/index.md to the users, but I cannot sync README.md file with the code and make readme as simple as it can, so I have to do some else.

First, I should know how jsdoc2md works.

How jsdoc2md works

This is the main use case (render documentation) sequence:

1. User runs jsdoc2md example.js.

2. jsdoc-api is used to obtain the raw jsdoc data for the input source code provided. (a kind of JSON output)

   jsdoc-api详见：

   https://github.com/jsdoc2md/jsdoc-api

3. this data is transformed into something suitable for passing into a template by jsdoc-parse (which also adds support for the jsdoc2md-specific tags like @typicalname, 

   @done, @category etc).

4. jsdoc-parse详见：

   https://github.com/jsdoc2md/jsdoc-parse

5. the resulting template data is passed into dmd. This output is returned to the user.

   dmd详见：
   

   https://github.com/jsdoc2md/dmd

In order to pick function name from the full api doc, I learnt about dmd, it is the default output templates for jsdoc-to-markdown. It contains handlebars partials and helpers intended to transform jsdoc-parseoutput into markdown API document.

 handlebars详见：http://handlebarsjs.com/

For the wechaty document, I change two following dmd partials:

• link.hbs

• sig-link-parent.hbs

Wechaty Progress on JsDoc && jsdoc2md

Discussion history

Related Issue

@Huan, @ax4,@hczhcz, @William and I talked a lot about wechaty document on the following issues:

• issue73: [doc] To Embed Document in Wechaty Code for Generating Automaticly

• issue252: [doc] Contribute to the doc editing[ jsdoc / jsdoc2md / typedoc ] 

issue73详见：

https://github.com/chatie/wechaty/issues/73

issue252详见：

https://github.com/chatie/wechaty/issues/252

Related PR

Also, @hczhcz and @ax4 and I contribute a lot on the document:

• PR378: jsdoc2md may flush some pieces of the embedded doc

  https://github.com/Chatie/wechaty/issues/378
  

• PR380: fix jsdoc flush issue #378 and minor fix on the doc examples

  https://github.com/Chatie/wechaty/pull/380
  

• PR640: add documentation TODO entries

  https://github.com/Chatie/wechaty/pull/640
  

• PR725: add wechaty document

  https://github.com/Chatie/wechaty/pull/725
  

• PR321: Add JsDoc for Class Contact

  https://github.com/Chatie/wechaty/pull/321
  

Doc basic line

For the convenience of developers, our doc guideline as follows:

1. Simple and clear

2. Generate markdown for better readable version control and GitHub page hosting.

Auto-doc working flow

1. Develop in TypeScript

2. Embedded doc insert in TypeScript

3. Compile TypeScript into JavaScript, using npm run dist

4. Run jsdoc / jsdoc2md, using npm run doc

5. Get the final doc, in index.md, config it to chatie.io/wechaty

 index.md详见：

https://github.com/Chatie/wechaty/blob/master/docs/index.md

 chatie.io/wechaty详见：

http://chatie.io/wechaty/

Wechaty Jsdoc file

We embed doc into the following file:

• src/wechaty.ts

  https://github.com/Chatie/wechaty/blob/master/src/wechaty.ts
  

• src/message.ts

  https://github.com/Chatie/wechaty/blob/master/src/message.ts
  

• src/room.ts

  https://github.com/Chatie/wechaty/blob/master/src/room.ts
  

• src/contact.ts

  https://github.com/Chatie/wechaty/blob/master/src/contact.ts
  

• src/friend-request.ts

  https://github.com/Chatie/wechaty/blob/master/src/friend-request.ts

Wechaty jsdoc2md progress

1. Generate jsdoc2md file

Using the following command can generate document easily.

jsdoc2md dist/src/{wechaty,room,contact,friend-request,message}.js dist/src/puppet-web/friend-request.js>> docs/index.md

2. Use template to Sync Readme with api doc

Actually, the first step is enough, but I think we need insert and sync all of the API docs into README, so I use a template by the following command:

jsdoc2md --template docs/partials/README.hbs dist/src/{wechaty,room,contact,friend-request,message}.js dist/src/puppet-web/friend-request.js>> README.md

Then add the partials to show the API directory, because the full doc is too big to put in README, and it is not necessary.

3. Linkable Code References

After the second step, I found the link jsdoc2md generate is an anchor link(#), it means I cannot link it to other pages(http://chatie.io/wechaty), this is very inconvenient for readers. 
Inspired  by  [jsdoc2md-issue-123]

 @KevinAst using jsdoc-to-markdown wrote a beatutiful doc: astx-redux-util. 

jsdoc2md-issue-123详见：

https://github.com/jsdoc2md/jsdoc-to-markdown/issues/123

 astx-redux-util详见：

https://astx-redux-util.js.org/1.0.0/

I found maybe I can created a custom partial too. 
Then I override the following templates in docs/partials/overrides, adding http://chatie.io/wechaty in the link:

• link.hbs

• sig-link-parent.hbs

This is the reason why I add the following script in package.json :

jsdoc2md --partial docs/partials/overrides/*.hbs --template docs/partials/README.hbs dist/src/{wechaty,room,contact,friend-request,message}.js dist/src/puppet-web/friend-request.js>> README.md

--partial command override 

link.hbs and sig-link-parent.hbs

Then, all done!

To Contributor: How to add jsdoc when contributing

For other developers, I tried my best to make it easier to add doc, just the following 2 steps:

1. Add jsdoc in your code like the following shows.

/** This is a description of the foo function. */
function foo() {
}

2. Run the following command

npm run doc

Then you can find the generated jsdoc here:

详见：https://github.com/Chatie/wechaty/blob/master/docs/index.md

Cheers!

http://blog.chatie.io/

https://github.com/chatie/wechaty

专注于智能对话服务的创业公司

欢迎关注“句子互动”