The future of better-docs

[wojtek-krysiak]

Current implementation / limitations

better-docs is based on jsdoc in a way that it extends before the "parse" phase and after in "render" phase:

BEFORE ---> produced JavaScript ---> JSDoc ---> AFTER ---> rendered template

In the "Before" phase:

• adds all the new tags like @section @ogTags @category @subcategory @new etc to DocLets (some of them are on beta branch btw)
• parses PropTypes from react components
• in case of typescript files - it changes interface to @interface and type to @typedef. Take a look [at my article here] t(https://medium.com/@wojciechkrysiak/typescript-jsdoc-better-docs-7c03b6ea04df) to see more details. Then it converts ts to 'js' and passes back to JSDoc

In the After phase:

• takes the data from the Before phase and puts it on modified "default" template from JSdoc so it looks pretty.

What is the problem with that

• Having JSDoc in the middle we are restricted by it. ** So implementing some things (like js decorators) could be not possible until JSDoc implements it) ** all the issues from JSDoc: https://github.com/jsdoc/jsdoc/issues applies here as well

• converting TS to JS causes super strange issues sometimes. ** JSDoc relies on "clear" code without blank lines between comments and declarations etc. But ts parser sometimes adds them. This results in super strange behaviour where documentation is empty. Also, it simply forbids us from implementing things like @decorators as well (they by default creates empty lines)

The solution

The only solution I see is to write our own js/ts parser which will extract DocLets from js/ts files as JSDoc does, so we can control it in 100% and add new amazing features like:

• -- watch mode
• auto refresh
• @param name (where type is taken from TypeScript)
• ts enums, decorators etc.

Proposed toolset

typescript parser - we currently use this to extract types and interfaces

• works like this: https://astexplorer.net/
• https://basarat.gitbook.io/typescript/overview/ast/ast-tip-children - this is the dev friendly docs

on https://astexplorer.net/ there are more parsers but typescript seems to be the best because:

• parses TS
• parses JSDoc tags (some other omits them in AST)

ETA

This is a very big task, and since we are working on admin-bro right now I don't expect this to be done in 2020 - most probably early 2021.

Related tasks:

#113 #106 #105 #86 #76 #68 #64 #42

[cowwoc]

@wojtek-krysiak Is there a possibility of building on top of https://github.com/microsoft/tsdoc or https://typedoc.org/ instead of building your own parser? Your output is much nicer than theirs, but maybe their parser is good enough.

[wojtek-krysiak]

Hi - yes I was thinking about that as the first step (even before we added typescript support to better-docs) - and:

1. https://github.com/microsoft/tsdoc - when you go to the example page it doesn't work with the following code which is parsed well by better-docs right now (example from admin-bro):

/**
 * Context object passed to a PageHandler
 *
 * @alias PageContext
 * @memberof AdminBroOptions
 */
export type PageContext = {
  /**
   * current instance of AdminBro. You may use it to fetch other Resources by their names:
   */
  _admin: AdminBro;
    /**
   * Currently logged in admin
   */
  currentAdmin?: CurrentAdmin;
    /**
   * view helpers
   */
  h: ViewHelpers;
}

basically, this is not a standard tsdoc comment, but it simplifies a loot documenting code right now and we would like to keep it.

2. TypeDoc

I briefly checked that out when we added typescript support (again as an alternative to ts), and:

• it restrict us to just typescript
• the same problem with tsdoc remains
• It looks that it works on entire typescript project (it has to import all files and build ts project) - where in better-docs you can import one ts file, one jsfile and decide which types will go to the docs.

[futurGH]

How is this going; is there any way to contribute to this effort?