Libdoc shows keyword arguments separately and lists their names, "kind" (positional-only, varargs, ...), possible type (str, int, ...) and possible default value. There is, however, no way to include argument documentation in this listing. Instead, arguments need to be documented as part of the normal keyword documentation using whatever approach found usable. Libdoc also shows return value type, but it does not support documentation either.

We should change this and make it possible to specify argument and return value documentation explicitly so that it could be listed along with other argument and return value related information. This syntax should also play well with other tools such as IDEs and API doc generators. In practice we thus should use syntax that's used for arguments with Python normally. Unfortunately there is no official standard for that and different projects have used different approaches. The three most commonly used argument documentation styles are:

1. The Sphinx style. This is what we currently use with Robot's API docs. In that usage it has worked fine, but the syntax is pretty complicate and verbose. It also doesn't render nicely as Markdown that we plan to support with Libdoc (Libdoc: Support documentation written with Markdown #5304).
2. The NumPy style. This style is used primarily in the scientific Python circles. but nobody would prevent us from using it. It's simpler than the Sphinx style, but it still requires quite a bit of markers and doesn't work with with Markdown.
3. The Google style. This is the simplest format and works very well also in source code. An example using this style is below.

def example(first: int, second: float) -> float:
    """Example keyword.

    Args:
        first: The doc for the first parameter.
        second: Also the second parameter has documentation.
          It is split to multiple lines.

    Return:
        The sum of the given arguments.
    """
    return a + b

The Google style is my clear favorite. It could be used both with library keywords and user keywords, and we probably could support it both with Markdown and with Robot's own documentation format. The Google style has it's own problems, though::

1. Also this syntax doesn't work too well with standard Markdown. For example, the block of tests starting with Args: is parsed as a single paragraph so you end up with a paragraph starting with Args: second: The doc for the first .... The situation gets better if you add an empty line after Args:. In that case rest of the block is considered a code block and rendered as preformatted text. Not great but massively better than alternatives.
2. Also the old Robot format parses the whole Args: block as a paragraph and this time adding an empty row just causes there toe be two paragraphs. We may need to enhance the Robot format to support this argument documentation style better.
3. The syntax isn't specified in detailed level and there are various flavors with the headers. The spec I linked above lists headers Args:, Returns:/Yields: and Raises:, but I've seen also seen Args: replaced with Arguments:orParameters:` and some extra headers being used.

Luckily we can solve these problems with some extra work:

1. Decide which flavor of the Google style we support. This includes deciding which headers to support and whether we should support specifying argument types (type hints generally work better).
2. Implement a parser for the flavor we support. It should read argument docs so that we can add them to Libdoc model along with argument names and types. Docs should then be shown in the Libdoc UI along with other argument information.
3. Remove argument documentation from the overall docs. No need to show the same information twice and this also avoids problems with Markdown formatting.