typhonrt
commented
7 years ago Hi @psyrendust... Welcome! Indeed this is an interesting and challenging feature to implement, but one that is worthy as it further hardens the runtime. It also shows off the flexibility of the architecture of TJSDoc which is internally highly modular and eventbus based. The watcher functionality will actually be implemented as a plugin. I already have added in several commits to support keep alive functionality and have a proof of concept plugin implementation that generates doc data for any updated files and gracefully handles parser / doc tag processing errors for incomplete updates.
The next step is to work out the merging / resolution logic as to generate docs for a project it's necessary to merge new data with the existing complete set of project data already parsed. The plugin basically works by TJSDoc making a complete pass then in the onComplete plugin callback a keep alive flag is set and file watching enabled by gaze. The cool thing is that TJSDoc already works internally using source globs, so it smoothly works with gaze and should support addition / deletion of files eventually as well (again just the merging / resolution logic to work out).
You can check out the initial proof of concept plugin code here. I'm pretty excited as it should take around ~3-5 seconds to do live updates to individual files once complete. It should be noted that this plugin is really for development / rapid documentation prototyping with the default doc templates. IE there is no easy way to let most other plugins in on the regeneration action though some publisher specific plugins should work as long as they don't rely on any data gathered during the process of a complete normal execution of TJSDoc. As a standalone plugin for rapid doc prototyping though it should work out well.
I feel pretty confident in getting a fully working solution tomorrow for changes.. Additions & deletions may be a bit dicier.
One of the things I kinda dislike about esdoc, was that if you were running your own watch task on your source and you make a single doc change, esdoc would have to run on the entire code base again to generate the documentation.
It would be great if it was possible to have a watch task that would only run on the diff changes. This would be a great addition if you are in documentation writing mode.