RF Doc style Proposal

[kstine]

Keywords - Documentation (Proposed) Purpose: To leverage the VSCode Extension "Robot Framework Language Server" ability to preview Keyword Documentation.

After reviewing a few docstring styles, the one that proved most adaptable to Robot Framework was from Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings It goes without saying that any part of Robot Framework that is Python should follow the docstring guidance from the PEP8 Python Style Guide.

The Bare Minimum Documentation should be always listed for every keyword and for every "*** Settings ***" section within a resource or robot file.

The minimum string used should be "None".

"None" is reserved for the case where the keyword is self defining.

"None" used for a resource or robot file is not acceptable.

Resource and Robot Files Provide a few lines describing what the file is for. It can be a simple as New Calls Page Object or REST API Endpoint Parsing Keyword Library Keywords- No arguments, no returns, no assertions Provide a one or two lines description of what the keyword does.

The description should be descriptive-style (Fetches rows from a Bigtable.) rather than imperative-style (Fetch rows from a Bigtable.).

Keywords- Arguments Basic argument documentation syntax:

This Is A Keyword With Arguments
  [Documentation]  This keyword does things.
  ...
  ...  Args:
  ...  - i_am_an_argument (str): required
  ...  - dict_var (dict):
  ...      required, expected keys [key1, key2, key3]
  ...  - i_am_an_arg_with_default (str): defaults to [None]
  ...  - a_var_assigned_to_a_var (int):  defaults to [$GLOBAL_INT_VAR]
  [Arguments]  ${i_am_an_argument}  ${dict_var}  ${i_am_an_arg_with_default}=${NONE}. ${a_var_assigned_to_a_var}=${GLOBAL_INT_VAR}

As you can see there is an general pattern. • Initial Documentation line(s) • Blank return line • "Args:" header • List of the arguments starting with a "- " (translates to a bullet point in the intelligent description popup) • An argument line has: name of argument without scalar notation, type in parens, colon, description • Typing is the same as standard Python typing. • Descriptions usually start with whether the argument is required or defaulted (optional) • If needed the argument description can be placed below the arg line, and indented. • When optional the default value is put in a set of brackets.

Keywords- Returns Basic return documentation syntax:

This Is A Keyword With Arguments
  [Documentation]  This keyword does things.
  ...
  ...  Returns:
  ...  - (str): returns a string

As you can see, the syntax is similar. • Initial Documentation line(s) or an "Args" section • Blank return line • "Returns:" header • List of the returns starting with a "- " (translates to a bullet point in the intelligent description popup) • An returns line has: type in parens, colon, description • Typing is the same as standard Python typing. • Descriptions are as needed.

If a Keyword creates a GLOBAL, SUITE, or TEST variable the pattern changes slightly:

Create The Global Int Variable
  [Documentation]  Creates a global int variable
  ...
  ...  Returns:
  ...  - GLOBAL_INT_VAR (int): GLOBAL

• The pattern is changed to include the constant cased variable without scalar notation and the scope listed in all caps in the beginning of the description.

Keywords- Assertions This section is only for keywords that have an assertion type keyword (i.e. Should...)

Verify That Normalcy Has Been Attained
  [Documentation]  Is it normal?
  ...
  ...  Asserts:
  ...  - Should Be Equal: established that things are equal

The syntax provides quick clarity on what the keyword is asserting. • Initial Documentation line(s) or an "Args" section or "Returns" section • Blank return line • "Asserts:" header • List of the returns starting with a "- " (translates to a bullet point in the intelligent description popup) • An asserts line has: Name of Asserting Keyword, colon, description • Description should be as detailed as needed