-
-
Notifications
You must be signed in to change notification settings - Fork 196
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
Document the return value of AccessDialog() #1114
Conversation
@@ -37,7 +37,8 @@ | |||
@subtitle: Subtitle for the dialog | |||
@body: Body text, may be "" | |||
@options: Vardict with optional further information | |||
@response: Numeric response | |||
@response: Numeric response. A value of 0 indicates that the user has | |||
agreed to grant permission. Any other value is treated as a refusal. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(almost) all the other impl.portal
just state Numeric response
too - it'd be nice to update all those, and ideally to something like: "The value returned as the response argument in the #org.freedesktop.portal.Request::Response for the corresponding Request". This way you get the automatic link to where the documentation for the return values is.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure I understand. What is "the #org.freedesktop.portal.Request::Response for the corresponding Request" in this case?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Huh, indeed, this is one (of the few?) that doesn't have an immediately corresponding request in the client API. I think in that case something like "The value range of the response matches the values allowed for #org.freedesktop.portal.Request::Response" for this one. Still would be nice to update the others though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated.
It's not rendering correctly; I'm not entirely sure why. |
Looks like the I'm not entirely sure what format this is, so I'm not sure where to look for its documentation. How do I add an actual link to the anchor? |
Oh, there's an example right above it 🤦 I tried this: diff --git a/data/org.freedesktop.impl.portal.Access.xml b/data/org.freedesktop.impl.portal.Access.xml
index 29a9f70..5759e02 100644
--- a/data/org.freedesktop.impl.portal.Access.xml
+++ b/data/org.freedesktop.impl.portal.Access.xml
@@ -37,7 +37,7 @@
@subtitle: Subtitle for the dialog
@body: Body text, may be ""
@options: Vardict with optional further information
- @response: Numeric response. The values allowed match the values allowed for #org.freedesktop.portal.Request::Response signal.
+ @response: Numeric response. The values allowed match the values allowed for <link linkend="#gdbus-signal-org-freedesktop-portal-Request.Response">#org.freedesktop.portal.Request::Response</link> signal.
@results: Vardict with the results of the call
Presents a "deny/grant" question to the user. But it fails to build:
I'm not sure how to work around this. Any insight is welcome. |
We're reworking the docs system on #1157 but this is good to have already |
Sphinx sound like a great choice 👍 |
Closes: #1041