DevCmd's exec* methods should be documented (in .d.ts)
PatrickLehnerXI opened this issue · comments
The process execution functions (
execPipedetc.) exposed by thedevcmdpackage aren't currently publicly documented. This should be added to make it easier to understand their usage and behavior, esp. the differences between the various functions we have.
Note: This feedback was provided internally at XITASO, so I'm creating this issue for tracking.
After short research, I found out that the actual implementations in ProcessExecutor are documented, but this documentation isn't exposed because we re-export the methods of our default ProcessExecutor instance in packages\devcmd\src\process\index.ts.
I'm not sure if we can use @inheritdoc in JSDoc to copy doc-strings from other elements like you can do in C#. If not, we should copy the documentation for the moment to make it accessible to users.
After a little more research and some trying around, I confirmed what I was afraid of: there is no way to copy another element's doc string in a way that VS Code shows inline.
So for the moment, I manually copied the doc strings for the two functions that are already documented, so these are now visible in the IDE and in the .d.ts file. (PR will follow in a moment.)
We are going to need to figure out if we can do more for this in the future. Any ideas are welcome here.
NB: This issue is related to #16, but addresses specifically the re-export of the exec* methods, so I'm keeping this around for the moment.