Skip to content
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

The future of better-docs #115

Open
wojtek-krysiak opened this issue Oct 28, 2020 · 3 comments
Open

The future of better-docs #115

wojtek-krysiak opened this issue Oct 28, 2020 · 3 comments

Comments

@wojtek-krysiak
Copy link
Contributor

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:

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

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
Copy link

cowwoc commented Oct 28, 2020

@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
Copy link
Contributor Author

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.

  1. 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
Copy link

futurGH commented May 18, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants