Docsrings for the Next Runner, Resolver, and new functionality

[pevogam]

Hi, I wanted to try out a bit more of the code for the new parallel runner and resolver modules but I had trouble with severe lack of documentation, in particular no doctrings of any kind and no argument types/descriptions for public API of runner_nrunner as well as resolver modules. Are there plans to add these docstrings before the serial runner is deprecated? I am asking in particular because some of us will have to do migrations before the serial runner is dropped and dependencies are broken and we will definitely need some docstring argument types and sentences in order to figure out the whisles and blows of all internal workings.

[willianrampazzo]

Hi @pevogam, I hope you don't mind that I moved your issue to a discussion on GitHub.

A good starting point to learn about the NRunner is https://avocado-framework.readthedocs.io/en/latest/guides/contributor/chapters/runners.html

Another document that may help is related to the NRunner state machine at https://avocado-framework.readthedocs.io/en/latest/blueprints/BP003.html

The docstrings are, indeed, valuable from a developer's point of view. As I work on any task related to the NRunner, I'll do my best to update the missing docstrings I find.

[pevogam]

Hi @pevogam, I hope you don't mind that I moved your issue to a discussion on GitHub.

Hi @willianrampazzo, I originally meant this as an issue since it is probably part of the TODO and thus something worth tracking and reporting. It was less of a question and more of a request for whenever possible. And I don't think we are discussing whether to add the docstrings or not either so perhaps another reason why it is more of a reported issue. This being said, you know better the right assignment and I guess you prefer if this is started as an inquiry of some sort.

A good starting point to learn about the NRunner is https://avocado-framework.readthedocs.io/en/latest/guides/contributor/chapters/runners.html

Another document that may help is related to the NRunner state machine at https://avocado-framework.readthedocs.io/en/latest/blueprints/BP003.html

The docstrings are, indeed, valuable from a developer's point of view. As I work on any task related to the NRunner, I'll do my best to update the missing docstrings I find.

AFAIR I participated in reviewing some of these blueprint so I am aware of the concepts. Unless you mean these also explain implementation details related to the code itself like argument types, etc. Then I might have missed something indeed.

[willianrampazzo]

Hi @willianrampazzo, I originally meant this as an issue since it is probably part of the TODO and thus something worth tracking and reporting. It was less of a question and more of a request for whenever possible. And I don't think we are discussing whether to add the docstrings or not either so perhaps another reason why it is more of a reported issue. This being said, you know better the right assignment and I guess you prefer if this is started as an inquiry of some sort.

Okay, in this case, I think an issue listing the files with missing docstrings would fit better for the purpose. To me, your text looked more like a question than a request to fulfill any specific missing docstring, that is why I moved it to the discussions session. Sorry about that :)

[pevogam]

Hehe, I state the issues in a polite manner which could make them sounds like questions. My point is to not come and order around what needs to be done. You as maintainers know best.

[clebergnu]

Hi @pevogam ,

There's a lot to improve with regards to documentation, specially docstrings. But, before moving further, I'd like to know if you're aware of the following docs:

• https://avocado-framework.readthedocs.io/en/86.0/guides/contributor/chapters/runners.html

• https://avocado-framework.readthedocs.io/en/86.0/guides/contributor/chapters/plugins.html#new-test-type-plugin-example

• https://avocado-framework.readthedocs.io/en/86.0/blueprints/BP003.html

While not proper documentation, we're also discussing improvements wrt messages exchanged between runners and the nrunner's status server/repo.

[pevogam]

Indeed, I expect that most arguments are almost self-documenting through the use of consistent argument names and some documentation like this. I will take a look at this for now, trying to map various function arguments to the concepts there wherever possible.