Libdoc: Include automatic argument conversion info #4160
Comments
|
Thinks to remember:
|
Move responsibility mostly to TypeConverter that is responsible on conversion as well. This way information shown by Libdoc ought to be consistent with actual conversion. It also makes it easier to get information about built-in converters to Libdoc later (#4160).
|
Spec files currently have data types listed so that enumerations, typed dicts and newly added custom converters all have their own listings. In JSON specs it looks like This separation isn't too convenient in the common case where you want to operate with all types. For example, Libdoc's own HTML output needs to combine these lists together and sort them separately to get them into alphabetical order. Instead of adding new info about standard converters as another listing, a decision was made to store all type information as a single Each type in the To avoid backwards incompatibility problems, the old |
`types` has all different types as a list with `type` telling are they emuns, typed dicts or custom types. `dataTypes` had different entries for sifferent types. This change is preparation for adding information about all converted types to Libdoc specs (#4160). It will be easier to add them, and to process them, in same `types` list than adding yet another entry under `dataTypes`. As `libdoc.html` changes show, having different types in a single list is more convenient already now. For backwards compatibility, old `dataTypes` is still written. It is also parsed if `types` is not present.
|
Type documentation will be stored under |
Initial work. Actual docs mostly missing.
Only int and bool had docs earlier, others had TODO. Also enhance this docs in the User Guide a bit.
|
With the latest changes this issue is about to get ready. Things that still need to be done:
The last point is something where others could help. Unfortunately it doesn't seem to be possible to attach HTML files to these issues so I needed to find a place where to host an example file or provide instructions how to generate one with all possible type docs. |
|
An example file is now available at http://uttermost-fairies.surge.sh/out.html. As mentioned above, proofreading the docs would be highly appreciated and other comments are obviously valuable as well. |
Info is stored to specs under `accepts` and shown also in HTML. This info makes it possible to separate normal Enums from IntEnums. In HTML that knowledge is used for showing IntEnum values.
Hopefully the final part of #4160.
|
Above changes added information about accepted types to outputs, added documentation to the User Guide, and also changed the usage listing of types to more compact variant. An example with all the latest changes is available at https://ruthless-scent.surge.sh/out.html. As a more realistic example, SeleniumLibrary documentation generated with the latest changes is at https://ruthless-scent.surge.sh/SeleniumLibrary.html. I consider this issue done but it is likely that HTML output will still be changed before RF 5.0 final. Comments regarding to this functionality in general are still appreciated either here or in the #devel channel on our Slack. |
|
Little style tweaks to the Usages list still in the above commit. New examples available: |
|
Thanks @samipe for creating modal dialog where the type info is shown. Lot nicer than listing this info at the end of the documentation. |
Currently Libdoc includes information about Enums and TypedDicts in its outputs (#3607, #3783). We are adding support for custom argument converters (#4088) and part of that is including information about these custom types in Libdoc outputs as well. It would be convenient if outputs would also contain information about types we automatically convert into. We could basically include same information that's in the User Guide. Information should be added only to types that are actually used by the library.
The text was updated successfully, but these errors were encountered: