feat(go): comments are enhanced to provide better developer experience (

#1536) ## 🧭 What and Why 🎟 JIRA Ticket: https://algolia.atlassian.net/browse/APIC-665 To improve the developer experience, we need better documentation on our code so the users will not need to switch between external documentation and code again and again. ### Changes included: - Added and improved comments on all the requests. - Some pieces are reordered to give easier navigation when using the package. ## 🧪 Test Nothing changed functionally, generated commit can be checked to see examples of the comments.
algolia · May 16, 2023 · 72755c1 · 72755c1
1 parent 67e4fde
commit 72755c1
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 24 deletions.
diff --git a/templates/go/api.mustache b/templates/go/api.mustache
@@ -38,12 +38,6 @@ func HeaderParamOption(name string, val any) Option {
 
 {{#operation}}
   {{#hasParams}}
-  type {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request struct {
-{{#allParams}}
-	{{paramName}} {{^isPathParam}}{{^isFreeFormObject}}{{^isArray}}{{^isPrimitiveType}}*{{/isPrimitiveType}}{{/isArray}}{{/isFreeFormObject}}{{/isPathParam}}{{{dataType}}}
-{{/allParams}}
-}
-
 func (r *{{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request) UnmarshalJSON(b []byte) error {
 	req := map[string]json.RawMessage{}
 	err := json.Unmarshal(b, &req)
@@ -70,46 +64,80 @@ func (r *{{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/
   return nil
 }
 
+// {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request represents the request with all the parameters for the API call.
+type {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request struct {
 {{#allParams}}
-{{^required}}
-{{#description}}
-// {{.}}
-{{/description}}
-{{#isDeprecated}}
-// Deprecated
-{{/isDeprecated}}
-func (r {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request) With{{#lambda.titlecase}}{{paramName}}{{/lambda.titlecase}}({{paramName}} {{^isFreeFormObject}}{{^isArray}}{{^isPrimitiveType}}*{{/isPrimitiveType}}{{/isArray}}{{/isFreeFormObject}}{{{dataType}}}) {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request {
-	r.{{paramName}} = {{paramName}}
-	return r
+	{{paramName}} {{^isPathParam}}{{^isFreeFormObject}}{{^isArray}}{{^isPrimitiveType}}*{{/isPrimitiveType}}{{/isArray}}{{/isFreeFormObject}}{{/isPathParam}}{{{dataType}}}
+{{/allParams}}
 }
 
-{{/required}}
-{{/allParams}}
 {{#isDeprecated}}
 // Deprecated
 {{/isDeprecated}}
-//@return {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request
+//New{{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request creates an instance of the {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request to be used for the API call.
 func (c *APIClient) NewApi{{{nickname}}}Request({{#requiredParams}} {{paramName}} {{^isPathParam}}{{^isFreeFormObject}}{{^isArray}}{{^isPrimitiveType}}*{{/isPrimitiveType}}{{/isArray}}{{/isFreeFormObject}}{{/isPathParam}}{{{dataType}}} {{^-last}},{{/-last}}{{/requiredParams}}) {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request {
 	return {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request{
 		{{#requiredParams}}
 		{{paramName}}: {{paramName}},
 		{{/requiredParams}}
 	}
 }
+
+{{#allParams}}
+{{^required}}
+// With{{#lambda.titlecase}}{{paramName}}{{/lambda.titlecase}} adds the {{paramName}} to the {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request and returns the request for chaining.
+{{#isDeprecated}}
+// Deprecated
+{{/isDeprecated}}
+func (r {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request) With{{#lambda.titlecase}}{{paramName}}{{/lambda.titlecase}}({{paramName}} {{^isFreeFormObject}}{{^isArray}}{{^isPrimitiveType}}*{{/isPrimitiveType}}{{/isArray}}{{/isFreeFormObject}}{{{dataType}}}) {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request {
+	r.{{paramName}} = {{paramName}}
+	return r
+}
+
+{{/required}}
+{{/allParams}}
 {{/hasParams}}
-// {{nickname}} wraps {{nickname}}WithContext using context.Background.
+/*
+{{operationId}} {{{summary}}} Wraps {{nickname}}WithContext using context.Background.{{^summary}}Method for {{operationId}}{{/summary}}
+{{#notes}}
+
+{{{unescapedNotes}}}
+{{/notes}}
+
+Request can be constructed by NewApi{{operationId}}Request with parameters below.
+ {{#allParams}}
+ @param {{paramName}} {{dataType}}{{#description}} - {{{.}}}{{/description}}
+ {{/allParams}}
+ {{#returnType}}@return {{{.}}}{{/returnType}}
+{{#isDeprecated}}
+
+Deprecated
+{{/isDeprecated}}
+*/
 {{#isDeprecated}}
 // Deprecated
 {{/isDeprecated}}
 func (c *APIClient) {{nickname}}({{#hasParams}}r {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request,{{/hasParams}} opts ...Option) ({{#returnType}}{{^isArray}}{{^returnTypeIsPrimitive}}*{{/returnTypeIsPrimitive}}{{/isArray}}{{{.}}}, {{/returnType}}error) {
   return c.{{nickname}}WithContext(context.Background(), {{#hasParams}}r,{{/hasParams}} opts...)
 }
 
-// {{{description}}}{{#returnType}}
-//  @return {{{.}}}{{/returnType}}
+/*
+{{operationId}} {{{summary}}}{{^summary}}Method for {{operationId}}{{/summary}}
+{{#notes}}
+
+{{{unescapedNotes}}}
+{{/notes}}
+
+Request can be constructed by NewApi{{operationId}}Request with parameters below.
+ {{#allParams}}
+ @param {{paramName}} {{dataType}}{{#description}} - {{{.}}}{{/description}}
+ {{/allParams}}
+ {{#returnType}}@return {{{.}}}{{/returnType}}
 {{#isDeprecated}}
-// Deprecated
+
+Deprecated
 {{/isDeprecated}}
+*/
 func (c *APIClient) {{nickname}}WithContext(ctx context.Context, {{#hasParams}}r {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request,{{/hasParams}} opts ...Option) ({{#returnType}}{{^isArray}}{{^returnTypeIsPrimitive}}*{{/returnTypeIsPrimitive}}{{/isArray}}{{{.}}}, {{/returnType}}error) {
 	var (
     postBody     any
@@ -305,5 +333,6 @@ func (c *APIClient) {{nickname}}WithContext(ctx context.Context, {{#hasParams}}r
 	{{/returnType}}
 	return {{#returnType}}returnValue, {{/returnType}}nil
 }
+
 {{/operation}}
 {{/operations}}
diff --git a/templates/go/client.mustache b/templates/go/client.mustache
@@ -37,7 +37,7 @@ type APIClient struct {
 	transport *transport.Transport
 }
 
-// NewClient creates a new API client with appID, apiKey and region.
+// NewClient creates a new API client with {{#hasRegionalHost}}appID, apiKey and region.{{/hasRegionalHost}}{{^hasRegionalHost}}appID and apiKey.{{/hasRegionalHost}}
 func NewClient(appID, apiKey string{{#hasRegionalHost}}, region Region{{/hasRegionalHost}}) *APIClient {
 return NewClientWithConfig(Configuration{
 		AppID:         appID,
@@ -50,6 +50,7 @@ return NewClientWithConfig(Configuration{
 	})
 }
 
+// NewClientWithConfig creates a new API client with the given configuration to fully customize the client behaviour.
 func NewClientWithConfig(cfg Configuration) *APIClient {
   var hosts []*transport.StatefulHost