The Wayback Machine - https://web.archive.org/web/20201129172119/https://github.com/robotframework/robotframework/issues/3017
Skip to content

/ robotframework

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add return type to libdoc output #3017

Open
robinmackaij opened this issue Nov 30, 2018 · 7 comments
Open

Add return type to libdoc output #3017

robinmackaij opened this issue Nov 30, 2018 · 7 comments
Labels
enhancement good first issue help wanted priority: medium
Milestone
v4.0

Comments

@robinmackaij
Copy link

@robinmackaij robinmackaij commented Nov 30, 2018

With the support of type-hints Python signatures can give information on the type of returned values of a method. This could be used to improve the documentation generated by libdoc.

def my_func(foo: str, count: int) -> str: will give the following in the Argument column:
foo: str, count: int
This could be expanded to include the type of the returned value:
foo: str, count: int -> str (following the Python notation)
The header Arguments could be updated to Signature to reflect this additional information.

Things to consider (from Slack conversation):

  • Take into account user keywords that may have used [Return] setting
  • How to handle def(*, named_arg: str) -> int for forced named arguments methods. The resulting signature in the documentation (*, named_arg: str -> int) may confuse users that are not familiar with the new syntax to force named arguments. Note that the * cannot be omitted from the method signature since this would mean the method is no longer named-only.
  • How to handle types in a signature that are based on the typing module (typing.Union, etc.). Right now, they come up as typing.Union in the documentation, while the inclusion of the standard module (typing.) does not really give the user much information. Also, the more complex typing constructions (Optional, nested structures, etc.) could lead to very long and unusable documentation entries.
@mawentao119
Copy link

@mawentao119 mawentao119 commented Apr 4, 2019 •
edited

I usually deal with arguments in function. Such as "myvar = arg[1].encode('utf-8')" or other convertions .
If libdoc can generate [return] arguments, that will be more helpful to other members of the team.
@pekkaklarck
Copy link
Member

@pekkaklarck pekkaklarck commented Aug 15, 2019

Showing return type information in Libdoc output would certainly be useful. The biggest question is how to show that information. Options include:

  • Add new column. A drawback is that it takes some precious horizontal space with all keywords and most of the keywords don't have any return info to show. Could avoid this issue partly by not showing the column at all if its fully empty (we do that with keyword tags).

  • Show the info in the same column with arguments. There's lot of free space there at least with keywords that have longer documentation. The column could then be renamed to Signature but still needed to thing a bit how to actually show arguments and return values there.

I think the latter solution is better but this can still be discussed. Anyone interested to implement this? Shouldn't be overly complicated and I'd be happy to help and review pull requests.
@anandaprakash1979
Copy link

@anandaprakash1979 anandaprakash1979 commented Apr 25, 2020

Hi @pekkaklarck I am interested in implementing this request.
Can I work on this?
@pekkaklarck
Copy link
Member

@pekkaklarck pekkaklarck commented Aug 21, 2020

Sorry @anandaprakash1979 for missing your comment. Are you still interested in looking at this issue? RF 4.0 will contain also other LIbdoc HTML (e.g. #3586) and return value could be added at the same time.

We could also think should return value info be added to Libdocs XML outputs (libspec). Do you @fabioz see that as a useful enhancement? If yes, we should submit a separate issue about it.
@pekkaklarck pekkaklarck added this to the v4.0 milestone Aug 21, 2020
@pekkaklarck
Copy link
Member

@pekkaklarck pekkaklarck commented Aug 21, 2020

One thing to decide is how to handle user keywords that use the [Return] setting to specify the return value. That is the actual value, not type, so it's different information than what function annotations provide. Showing it would probably be useful anyway.
@Snooz82
Copy link
Collaborator

@Snooz82 Snooz82 commented Sep 15, 2020 •
edited

@pekkaklarck

For robot keywords it would be interesting that these keywords could return anything.
So i would propose that the Return Type of robot keywords that has [Return] or Return From Keyword ... is Any

So, for us (imbus) as user of the xml output, we would really be interested into getting an information if a keyword does return or does not return anything.
What is returned is not the most important issue. If this information is there, fine. If not, also ok.

i think also for Libdoc it would be a nice information.
@pekkaklarck pekkaklarck added the alpha 3 label Nov 2, 2020
@JockeJarre
Copy link

@JockeJarre JockeJarre commented Nov 20, 2020 •
edited

As discussed on Slack, would be nice if the @Keyword decorator allow setting the return type.

the proposed syntax:

@Keyword(types={'return': int})

It's compatible with how they are represented in func.annotations and would make implementation really easy. (Pekka)
There are also thoughts of having support for Unions as return type. Like Union[str, int]

Here is the whole slack thread https://robotframework.slack.com/archives/C0K0240NL/p1605819214419400?thread_ts=1604056554.147300&cid=C0K0240NL
@pekkaklarck pekkaklarck removed the alpha 3 label Nov 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement good first issue help wanted priority: medium
6 participants
@pekkaklarck @JockeJarre @mawentao119 @Snooz82 @anandaprakash1979 @robinmackaij
You can’t perform that action at this time.