twilio / twilio-go

A Go package for communicating with the Twilio API.
MIT License
280 stars 40 forks source link

docs: update godocs formatting #72

Closed thinkingserious closed 3 years ago

thinkingserious commented 3 years ago

Generated by https://github.com/twilio/twilio-oai-generator/pull/37

Update godocs formatting.

Checklist

thinkingserious commented 3 years ago

The // prefix is necessary for the comments, but not the *, those were added for better visual clarity:

Source: http://localhost:6060/src/github.com/twilio/twilio-go/twilio/rest/accounts/v1/api_default.go?s=1640:1766#L45

Screen Shot 2021-05-05 at 11 18 28 AM

Generated Docs: http://localhost:6060/pkg/github.com/twilio/twilio-go/twilio/rest/accounts/v1/#DefaultApiService.CreateCredentialAws

Screen Shot 2021-05-05 at 11 17 51 AM

Without the*'s:

Screen Shot 2021-05-05 at 11 34 01 AM

Screen Shot 2021-05-05 at 11 36 23 AM

If we add the * to just the #Notes section we get:

Screen Shot 2021-05-05 at 11 53 42 AM

Screen Shot 2021-05-05 at 11 41 44 AM

childish-sambino commented 3 years ago

From the resources mentioned here, I think we should remove the param/return stuff from the func comments. Params type should be updated to have inline comments on each field, similar to what is done for the models.

shwetha-manvinkurke commented 3 years ago

From the resources mentioned here, I think we should remove the param/return stuff from the func comments. Params type should be updated to have inline comments on each field, similar to what is done for the models.

What about the comments for the path params, which do not belong to params?

childish-sambino commented 3 years ago

What about the comments for the path params, which do not belong to params?

I'm okay with leaving them out since they're pretty self-documenting by their name. We can always add more details later.