Add more comments

Signed-off-by: Pierre-Emmanuel Jacquier <15922119+pierre-emmanuelJ@users.noreply.github.com>

v3/generator/client/client.go

@@ -15,6 +15,7 @@ import (
 	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
 )
 
+// Generate go client from OpenAPI spec servers into a go file.
 func Generate(doc libopenapi.Document, path, packageName string) error {
 	r, errs := doc.BuildV3Model()
 	for _, err := range errs {

v3/generator/operations/operations.go

@@ -16,6 +16,7 @@ import (
 	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
 )
 
+// Generate go requests from OpenAPI spec paths operations into a go file.
 func Generate(doc libopenapi.Document, path, packageName string) error {
 	model, errs := doc.BuildV3Model()
 	for _, err := range errs {
@@ -43,8 +44,10 @@ import (
 )
 `, packageName))
 
+	// Iterate over all paths.
 	err := helpers.ForEachMapSorted(model.Model.Paths.PathItems, func(path string, item any) error {
 		pathItems := item.(*v3.PathItem)
+		// For each path, render each operations (GET, POST, PUT...etc) schemas and requests.
 		return helpers.ForEachMapSorted(pathItems.GetOperations(), func(opName string, op any) error {
 			operation := op.(*v3.Operation)
 			funcName := helpers.ToCamel(operation.OperationId)
@@ -64,22 +67,22 @@ import (
 			}
 			output.Write(schemaRequest)
 
-			schemaParameters, err := renderMethodParameterSchema(funcName, operation)
+			schemaParameters, err := renderRequestParametersSchema(funcName, operation)
 			if err != nil {
 				return err
 			}
 			output.Write(schemaParameters)
 
-			method, err := serializeMethod(path, opName, funcName, operation)
+			request, err := serializeRequest(path, opName, funcName, operation)
 			if err != nil {
 				return err
 			}
 
-			if method == nil {
+			if request == nil {
 				return nil
 			}
 
-			m, err := renderMethod(method)
+			m, err := renderRequest(request)
 			if err != nil {
 				return err
 			}
@@ -178,21 +181,21 @@ func renderRequestSchema(name string, op *v3.Operation) ([]byte, error) {
 }
 
 const queryParamTemplate = `
-func {{ .MethodName }}({{ .ParamName }} {{ .ParamType }}) {{ .MethodReturn }} {
+func {{ .FuncName }}({{ .ParamName }} {{ .ParamType }}) {{ .FuncReturn }} {
 	return func(q url.Values) {
 		q.Add("{{ .ParamName }}", fmt.Sprint({{ .ParamName }}))
 	}
 }
 `
 
 type QueryParam struct {
-	MethodName   string
-	ParamName    string
-	ParamType    string
-	MethodReturn string
+	FuncName   string
+	ParamName  string
+	ParamType  string
+	FuncReturn string
 }
 
-func renderMethodParameterSchema(name string, op *v3.Operation) ([]byte, error) {
+func renderRequestParametersSchema(name string, op *v3.Operation) ([]byte, error) {
 	output := bytes.NewBuffer([]byte{})
 	query := bytes.NewBuffer([]byte{})
 
@@ -216,10 +219,10 @@ func renderMethodParameterSchema(name string, op *v3.Operation) ([]byte, error)
 				typ = schemas.RenderSimpleType(s)
 			}
 			if err := t.Execute(query, QueryParam{
-				MethodName:   name + "With" + helpers.ToCamel(p.Name),
-				ParamName:    helpers.ToLowerCamel(p.Name),
-				ParamType:    typ,
-				MethodReturn: name + "Opt",
+				FuncName:   name + "With" + helpers.ToCamel(p.Name),
+				ParamName:  helpers.ToLowerCamel(p.Name),
+				ParamType:  typ,
+				FuncReturn: name + "Opt",
 			}); err != nil {
 				return nil, err
 			}
@@ -246,7 +249,7 @@ func renderMethodParameterSchema(name string, op *v3.Operation) ([]byte, error)
 	return output.Bytes(), nil
 }
 
-type MethodTmpl struct {
+type RequestTmpl struct {
 	Comment        string
 	Name           string
 	Params         string
@@ -259,10 +262,10 @@ type MethodTmpl struct {
 	QueryParams    map[string]string
 }
 
-func serializeMethod(path, httpMethode, funcName string, op *v3.Operation) (*MethodTmpl, error) {
-	p := MethodTmpl{
+func serializeRequest(path, httpMethod, funcName string, op *v3.Operation) (*RequestTmpl, error) {
+	p := RequestTmpl{
 		Name:       funcName,
-		HTTPMethod: strings.ToUpper(httpMethode),
+		HTTPMethod: strings.ToUpper(httpMethod),
 	}
 	p.Comment = renderDoc(op)
 	params := getParameters(op, funcName)
@@ -298,8 +301,8 @@ func serializeMethod(path, httpMethode, funcName string, op *v3.Operation) (*Met
 	return &p, nil
 }
 
-func renderMethod(m *MethodTmpl) ([]byte, error) {
-	t, err := template.New("method.tmpl").ParseFiles("./operations/method.tmpl")
+func renderRequest(m *RequestTmpl) ([]byte, error) {
+	t, err := template.New("request.tmpl").ParseFiles("./operations/request.tmpl")
 	if err != nil {
 		return nil, err
 	}

v3/generator/schemas/schemas.go

@@ -20,7 +20,7 @@ var ignoredList = map[string]struct{}{
 	"snapshot-export": {},
 }
 
-// Generate go schema models from OpenAPI spec into a go file.
+// Generate go models from OpenAPI spec schemas into a go file.
 func Generate(doc libopenapi.Document, path, packageName string) error {
 	result, errs := doc.BuildV3Model()
 	for _, err := range errs {
@@ -122,7 +122,7 @@ func RenderSimpleType(s *base.Schema) string {
 }
 
 // renderSchemaInternal render a given libopenapi Schema into a buffer.
-// This function is mostly used recursively to render sub schemas into this buffer.
+// This function is mostly used recursively to render sub schemas object into this buffer.
 //
 // /!\ for every recusivity call, make sure to check schema reference before,
 // to prevent end up in infinite loop.
@@ -174,7 +174,7 @@ func renderSchemaInternal(schemaName string, s *base.Schema, output *bytes.Buffe
 		output.WriteString(doc)
 		output.WriteString(object)
 		return nil
-	// map represents an OpenAPI AdditionalProperties, it will always be map[string]Type
+	// map represents an OpenAPI AdditionalProperties, it will always be map[string]T
 	case "map":
 		output.WriteString(doc)
 		Map, err := renderSimpleMap(schemaName, s, output)
@@ -238,6 +238,7 @@ func renderArray(typeName string, s *base.Schema, output *bytes.Buffer) (string,
 		return definition + RenderSimpleType(item), nil
 	}
 
+	// Render new object from array schema into the buffer.
 	if err := renderSchemaInternal(typeName, item, output); err != nil {
 		return "", err
 	}
@@ -349,6 +350,7 @@ func renderObject(typeName string, s *base.Schema, output *bytes.Buffer) (string
 		}
 
 		if IsSimpleSchema(prop) {
+			// Render property type enum.
 			if len(prop.Enum) > 0 {
 				output.WriteString(renderSimpleTypeEnum(typeName+camelName, prop))
 				definition += camelName + " " + typeName + camelName + tag + "\n"
@@ -364,17 +366,20 @@ func renderObject(typeName string, s *base.Schema, output *bytes.Buffer) (string
 				definition += camelName + " " + RenderSimpleType(prop) + tag + "\n"
 				return nil
 			}
-
 			definition += camelName + " " + required + RenderSimpleType(prop) + tag + "\n"
 
 			return nil
 		}
 
+		// This is an OpenAPI free form object (deprecated).
+		// https://docs.42crunch.com/latest/content/oasv3/datavalidation/schema/v3-schema-object-without-properties.htm
+		// We recommand to use AdditionalProperties instead.
 		if len(prop.Properties) == 0 && prop.AdditionalProperties == nil {
 			definition += camelName + " map[string]any" + tag + "\n"
 			return nil
 		}
 
+		// Render additional properties (map).
 		if prop.AdditionalProperties != nil {
 			Map, err := renderSimpleMap(typeName+camelName, prop, output)
 			if err != nil {
@@ -384,6 +389,7 @@ func renderObject(typeName string, s *base.Schema, output *bytes.Buffer) (string
 			return nil
 		}
 
+		// Render new object from object property into the buffer.
 		if err := renderSchemaInternal(typeName+camelName, prop, output); err != nil {
 			return err
 		}
@@ -437,6 +443,7 @@ func renderSimpleMap(typeName string, s *base.Schema, output *bytes.Buffer) (str
 		return definition + RenderSimpleType(addl), nil
 	}
 
+	// Render new object from AdditionalProperties schema into the buffer.
 	if err := renderSchemaInternal(typeName, addl, output); err != nil {
 		return "", err
 	}