Documentation about how the code is organized

[Aquaticat]

Right now, there seems to be no documentation about how the source code is organized. I wasn't able to find out which code is doing what up to now.

I'm sure such documentation would be very helpful.

[surol]

The main source of the documentation is API docs

Other than that, what kind of details do you expect? I suspect it is pretty much useless to explain what directory contains what without proper explanation of how it works. While the latter is quite complicated.

Nonetheless, here you go:

• src/builins/ - built-in extensions. They always enabled.
  The full-scale extension mechanism still not implemented, so built-ins are the only extensions available.
• src/cli/ - the command line tool. It is transpiled into main executable.
• src/core/ - well, the core. The core is independent of Node.js.
  It performs the actual task execution using ZShell instance.
• src/os/ contains SystemZShell - a ZShell implementation for Node.js.
  It also includes various reporting engines.
• src/spec/ used by unit tests.

The core operates with tasks (ZTask) belonging to packages (ZPackage).
The tasks are built by parsing package scripts.
Then, the task execution plan constructed. It consists of task calls (ZCall). Those are tasks along with their execution parameters, attributes, prerequisites (other task to call before them), and parallel execution presets.
Once the execution plan constructed, the execution starts. Each task call executed by ZCall.exec(). The latter results to execution job (ZJob). A job is an abortable promise. It performs the actual work using a (singleton) ZShell instance.

A @run-z/optionz package is used to parse command line parameters. run-z has a non-standard command line interface, so popular CLI parsers won't work for it well enough. The @run-z/optionz package is an advanced tool developed to do the job.

A @run-z/exec-z package contains abortable promises implementation.

A @run-z/log-z is a structured logger used for reporting.

[Aquaticat]

Hi Ruslan,

I'm satisfied with the documentation of how to use it (API docs). I'm looking for the documentation of how it works.

Although it might be not very useful to explain what directory contains what without proper explanation of how it works, I believe that every bit of documentation helps.

According to your response and using my own understanding of the code, I would like to document which directory contains what and is doing what by including a readmd.md file in the directory. For files, by including <file-name>.md, what the file is doing can be documented too.

As I have limited understanding of the code, I would not include any information I'm not 100% sure, so these additions would be very incomplete.

If you are fine with this, I might create a pull request including these additions.

[surol]

I am definitely fine with any help with documenting things. I realize that documentation is one of the weakest spots of the project(s). Also, my English is not very strong.

Regarding the documenting individual files, I am not sure about the best approach. The implementation may change at any time, making such documentation obsolete. I typically prefer to place explanatory comments close to the (non-trivial) code fragments.
May be, it would be better to place explanations to per-directory readme files you've mentioned? In any case, having documentation is better than not...

[Aquaticat]

Alright then, I'll start with per-directory readme files first when (if) I have time. Both the directory's purpose and how it achieves this purpose are documented into this file.

You are right about documenting individual files, I didn't think about the situation when the file is changed. Thank you for bringing that up.

I think it's best to place the both the individual file's purpose and how it is implemented at the top of the file using a comment.

For files that do not have a way to write comments into (looking at you .json files), a <file-name>.<file-extension>.md file would be created as a sibling to the file, since such files typically would not and should not be renamed, moved, added, or removed.

However, I'm still undecided on the naming convention for such files, as to whether to include <file-extension> or not, and maybe an additional specifier .doc should be placed before the final extension .md. Currently, I believe <file-name>.<file-extension>.md should work well enough, but there's probably issues I have not thought about.
What do you think?

[surol]

Thanks,

I don't think there is something to document apart from TypeScript files. Configurations for development tools are well documented by those tools already. If that is meaningful, then mentioning what tools used and how in e.g. DEVELOPMENT.md with appropriate links to their documentation would work.

[Aquaticat]

You can thank me after I create the pull requests. My schedule is all filled up and I know I do not follow my plans well.

Okay. I think we should document those anyways. Also, I believe DEVELOPMENT.md should be reserved as a guide for other potential contributors, so I don't think we should use it for those purposes.

But no worries, I'll make sure to put those into separate pull requests, so you can reject documentations that are unneeded.