oxidecomputer / oxidecomputer/oxide.go
Improve Go doc comments for generated API methods
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 26
- Forks
- 6
- Avg merge
- 5h 33m
- Merged PRs (30d)
- 9
Description
The Go doc comments for generated API methods can be improved to include documentation for all method parameters.
For example, when an endpoint takes a request body the Go doc comment does not mention it.
// SiloPolicyUpdate: Update a silo's IAM policy
//
// Parameters:
// - `siloName`: The silo's unique name.
func (c *Client) SiloPolicyUpdate(siloName Name, j *SiloRolePolicy) (*SiloRolePolicy, error) {
Perhaps it should look like this.
// SiloPolicyUpdate: Update a silo's IAM policy
//
// Parameters:
// - `siloName`: The silo's unique name.
// - `j`: SiloRolePolicy is client view of a [`Policy`], which describes how this resource may be accessed
func (c *Client) SiloPolicyUpdate(siloName Name, j *SiloRolePolicy) (*SiloRolePolicy, error) {
There are other improvements that can be made to the Go doc comments, such as using Go doc links to link to other generated types.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the generated SiloPolicyUpdate method shown in the issue and trace how its Go doc comment is produced. Check how request-body parameters and links to generated types are represented, then verify that generated API methods document all parameters and use the intended Go doc links.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100