docs: include documentation for required parameters #964
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Currently it is unclear how to use some of the functions that return calls. Their required parameters are undocumented. This means a user of the library either needs to go look at the official docs page for the api or find the corresponding do method in the code and look for its private discovery json comment. This commit starts to add parameter descriptions for required fields, those that are passed to the Call method. Fixes: #950
|
@tbpg The first commit contains the actual code changes to the generator. LMK what you think of the formatting. I am open to suggestions! |
google-cla
bot
added
the
cla: yes
tbpg
reviewed
Mar 31, 2021
Comment on lines
968
to
971
| // - name: The resource name of the settings. Format is one of: * | ||
| // "projects/{project}/accessApprovalSettings" * | ||
| // "folders/{folder}/accessApprovalSettings" * | ||
| // "organizations/{organization}/accessApprovalSettings" |
There was a problem hiding this comment.
Can we make this show up properly?
There was a problem hiding this comment.
I don't think there is too much we can do here. It is hard to know intent of *. I don't think you can confidently tell where the last bullet should end. This is also a problem in other struct field and method docs already today.
|
Thanks |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Currently it is unclear how to use some of the functions that
return calls. Their required parameters are undocumented. This
means a user of the library either needs to go look at the official
docs page for the api or find the corresponding do method in the
code and look for its private discovery json comment. This commit
starts to add parameter descriptions for required fields, those
that are passed to the Call method.
Fixes: #950