Modify cli options and API in README #445
Conversation
README.md
Outdated
|
|
||
| **Members:** | ||
|
|
||
| - /\*\* |
There was a problem hiding this comment.
How about using typedoc?
There was a problem hiding this comment.
I didn't knew this package,
It seems pretty nice and match our use-case here.
I'll update the PR with it.
There was a problem hiding this comment.
@seiwonpark I've been quite busy lately.
I've implemented typedoc let me know what do you think before I can start working on automation.
There was a problem hiding this comment.
Pretty nice job! Interfaces are documented pretty nicely but not sure if classes are. (And some other fixes are required as well)
IMHO as @gustavohenke liked tables, current table-sorted README style seems better. And there seems to be more configuration to do to automate the process. So how about just let maintainers/contributors manually update the document more readable in current stage?
I've recommended typedoc to be like some use cases (e.g. chatgpt-api, and mermaid, ... and some other open sources). typedoc could be an option but this might be too early for concurrently in this stage(because to use it like the above libraries, pretty much comments should be fixed and written to fit the typedoc configuration).
So maybe setting the issue(automating documentation generation) as <Pending> and keep @Tarektouati's current README style that contains table-sorted document (but yes update document manually..) would be enough. Or, rather implementing separate library e.g. some-library-like-jsdoc-to-readme-parser would be a nice choice.
There was a problem hiding this comment.
Thanks !
Totally agree with @seiwonpark, as I see the generation result, I'm not totally convinced.
At least, it shows where codebase should be enhanced to have a better experience with it.
Let me know if we keep "automating documentation generation" task and create other PR in that direction, or maybe just drop the related commits.
There was a problem hiding this comment.
I like very much the new tables for each of the options! I think it might be possible to autogenerate those too (by inspecting yargs state).
I'm not sure I like how the TS docs generation is structured in the readme; it might be too much now. Maybe the typedoc suggestion (#445 (comment)) is good, but I haven't spent much more time looking into it. Will do once the PR is ready for review.
src/index.ts
Outdated
| @@ -18,11 +18,9 @@ import { LogTimings } from './flow-control/log-timings'; | |||
| import { RestartProcess } from './flow-control/restart-process'; | |||
| import { Logger } from './logger'; | |||
|
|
|||
| /** Logger options */ | |||
There was a problem hiding this comment.
I didn't go through the .md file yet, but it's my perception (and, well, it's what we do at Canva too) that // comments are usually not picked up by tooling (doc generators and IDEs), whereas /* */ comments are, so they work mostly as a file-internal comment that doesn't need to be exposed.
The old // Logger options was here mostly to create a section (just like there are others for input handling, restarting and so on below), I don't think it adds any value being in /* */ nor is it correct as the doc for ConcurrentlyOptions
cc @paescuj just because I think this has been an unwritten rule in this codebase :)
There was a problem hiding this comment.
I modified theses comments for ts-readme
they should be reverted after migrating to typedoc : (cf: #445 (comment))
| @@ -0,0 +1 @@ | |||
| TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false. | |||
There was a problem hiding this comment.
This file is generated by typedoc
| @@ -0,0 +1,264 @@ | |||
| # Class: Command | |||
There was a problem hiding this comment.
Moved to separate folder docs
Updated links in the README.md to this file as entry point for documentation
| #Generate documentation for the project based on Typescript types | ||
| pnpm exec typedoc | ||
|
|
||
| # Typedoc generates a README.md file in the docs folder, which is not needed |
There was a problem hiding this comment.
I think the comment is explicit here,
I couldn't find a way to avoid typedoc to regenerate README.md file in docs folder
This PR closes issue #444
It aims to
TODO :