Libdoc: Store information about enums and TypedDicts used as argument types in spec files

[fabioz]

This is from the discussion in: https://robotframework.slack.com/archives/C015KB1QSDN/p1593278603282300?thread_ts=1593190150.106700&cid=C015KB1QSDN

I don't have a ready-made solution, so, how to do it is up to discussion...

One suggestion: add the enums used by the libspec to the libspec.

i.e.: something as

<enums>
  <enum name="MyEnum">
    <value name="Emun1" value="val1"/>
    <value name="Emun2" value="val2"/>
  </enum>
</enums>

Then we could add <arg type="MyEnum">myarg</arg> in the libpsec (or officialize the myarg: MyEnum=Enum1, which is already being used) so that the language server could identify that properly.

[fabioz]

@pekkaklarck what do you think about the idea? Do you have any suggestions?

[pekkaklarck]

This idea sounds good to me but I'm not certain what's the best way to implement it. Need to think about that more and should also think how to show enums in Libdoc HTML outputs.

I don't think we can do changes to Libdoc specs in a patch version like RF 3.2.2 so need to wait for RF 3.3 or whatever the next bigger release will be.

[xylix]

We had a discussion with BrowserLibrary team at what our use case for this would be and for our documentation it would make most sense if we could have a types section after the keywords section containing all the enums (which we could expose via some get_data_types librarymethod). And then the keyword specific docs could link to those enums wherever they are mentioned.

[Snooz82]

XML have now this format:

<enum name="AssertionOperator">
  <doc>This is some Doc

  This has was defined by assigning to __doc__.</doc>
  <members>
    <member name="equal" value="=="/>
    <member name="==" value="=="/>
    <member name="&lt;" value="&lt;"/>
    <member name="&gt;" value="&gt;"/>
    <member name="&lt;=" value="&lt;="/>
    <member name="&gt;=" value="&gt;="/>
  </members>
</enum>

JSON:

"enums": [
      {
        "name": "AssertionOperator",
        "type": "Enum",
        "doc": "<p>This is some Doc</p>\n<p>This has was defined by assigning to __doc__.</p>",
        "members": [
          {
            "name": "equal",
            "value": "=="
          },
          {
            "name": "==",
            "value": "=="
          },
          {
            "name": "<",
            "value": "<"
          },
          {
            "name": ">",
            "value": ">"
          },
          {
            "name": "<=",
            "value": "<="
          },
          {
            "name": ">=",
            "value": ">="
          }
        ]
      }
    ]

[Snooz82]

Related to
#3783 Libdoc: Stored data types should be documented in LibDoc HTML
#3784 Libdoc: TypedDict types shall be documented in spec files as Enums are.

[pekkaklarck]

Let's merge this issue with storing TypedDict info in specs (#3784). They be implemented by the same PR (#3743) and have common issue about showing the info in HTML (#3783).