Add more details to robot docs

[EduKav1813]

The problem you're addressing (if any)

The current version of the robot documentation does not provide all necessary information that may help to develop or debug tests.

Describe the solution you'd like

Add the following information to the robot documentation:

1. Type hints for the arguments. If I see something like: Arguments: item it would help to know what type it is.
2. The type hints for the return values. The same as in the previous one.
3. Not all keywords have Documentation. Even if their name may be self-descriptive, it could confuse new users.

Where is the value to a user, and who might that user be?

Provide more relevant context for test developers.

Describe alternatives you've considered

No response

Additional context

No response

[m-iwanicki]

Not sure if it's correct place or if it should be in it's own issue but we should probably at least somewhat standardize keyword description format.
I would like if we not only had type hints of arguments and return values but also description of what this variable is for.

I'd also like if each description had requirements of when it can be used and maybe some side effects of using keyword e.g. whether keyword needs to be used inside Linux shell or during booting (e.g. after power on or reboot), whether using this keyword ends in reboot (especially if it's not easily deducible from description/name).
Often keyword doesn't need e.g. Power On used before it because it either uses it by itself or uses another keyword that uses it but in those cases it might be hard to know without diving deeply inside each keyword. Would help with contributing.md:

reduce the number of unnecessary power events, so tests can finish quicker

[philipandag]

some side effects of using keyword e.g. whether keyword needs to be used inside Linux shell or during booting

I totally agree. At this moment using the keywords pretty much requires first looking up how they work inside. As for this, I believe the only good fix would be to create a guideline somewhere in the OSFV repo, tell everyone to use it for new keywords and give someone the task of fixing the documentation for every existing keyword, test case and test suite according to the guidelines.

Not all keywords have Documentation.

There is a robocop check for that, just that it is being skipped for now because... not all keywords have documentation

    # TODO: add missing documentation for keywords and re-enable
    "0201:enabled:False",

There are many more checks skipped there, most marked with something like #TODO enable after fix.

[philipandag]

Type hints for the arguments. If I see something like: Arguments: item it would help to know what type it is.

Adding type annotations to keywords defined using RF is not supported right now with RF 7.0.1. There is an issue in their repository for this feature: robotframework/robotframework#3278.

As for now we could just require to manually say in the documentation what types are considered valid for a given argument.

[philipandag]

I'm working on creating the documentation guidelines here:
#637

I have proposed a template for KW documentation. It's hard to not notice that it is a bit long compared to existing documentations. Writing complex in-code documentation could negatively affect the process of creating and maintaining the keywords.

The documentation of test cases and test suites could probably also use some standarization and/or extension. I am not sure what we would wan't to include in them though. @mkopec Would you mind to share what you think?

[m-iwanicki]

@philipandag There is keyword length limit of maybe 50 lines in our pre-commit? I'm not sure if it's

open-source-firmware-validation/robocop.toml

Line 26 in b89f7ca

"0505:max_calls:50",

but from what I remember comments counted for this limit.
If it still does then we need to at least increase this limit or maybe add such a feature to robocop.

[philipandag]

@philipandag There is keyword length limit of maybe 50 lines in our pre-commit? I'm not sure if it's

I am aware of that and also thought that it might pose a problem. Defining keywords and their documentation in Python would certainly not trigger this robocop check, what's more, defining type hints for arguments and return values is possible if the keyword is implemented in Python. Rewriting most keywords in Python wouldn't be a good idea though, so I guess we need to document the KWds in RF.

Do you think such verbose documentation as in #637 i a good idea?

• Edit
  I have tested, that a long documentation does indeed trigger the robocop check for keyword number of calls.

[m-iwanicki]

I guess it's better than no/bad documentation. Not sure how I'd feel when every keyword in e.g. keywords.robot has such a long or even longer documentation but I'd really appreciate it in html documentation.
You should probably fix example so it displays correctly in html:

The biggest problem is with indentation