-
Notifications
You must be signed in to change notification settings - Fork 128
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
Comments
@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. |
Hi - yes I was thinking about that as the first step (even before we added typescript support to better-docs) - and:
basically, this is not a standard tsdoc comment, but it simplifies a loot documenting code right now and we would like to keep it.
I briefly checked that out when we added typescript support (again as an alternative to ts), and:
|
How is this going; is there any way to contribute to this effort? |
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:
interface
to@interface
andtype
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 convertsts
to 'js' and passes back to JSDocIn the After phase:
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:
@param name
(where type is taken from TypeScript)Proposed toolset
typescript parser - we currently use this to extract
types
andinterfaces
on https://astexplorer.net/ there are more parsers but typescript seems to be the best because:
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
The text was updated successfully, but these errors were encountered: