Merge pull request #20 from ythadhani/desc-as-comment

YANG descriptions as comments

.github/workflows/go.yml

@@ -126,7 +126,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v2
         with:
-          go-version: '1.x'
+          go-version: '1.18'
         id: go
 
       - name: Install required static analysis tools

generator/generator.go

@@ -106,9 +106,11 @@ var (
 	packageSuffix           = flag.String("path_struct_package_suffix", "path", "Suffix to append to generated Go package names, when split_pathstructs_by_module=true.")
 
 	// Nokia-defined flags
-	generateSwaggerCompliantCode = flag.Bool("generate_swagger_compliant_code", false, "Whether to generate tag keys: swaggertype, enums. Also, keyed lists would be modeled as slices.")
-	generateJsonTags             = flag.Bool("generate_json_tags", false, "Whether to generate tag key: json")
-	generateExtensionTags        = flag.Bool("generate_extension_tags", false, "Whether to generate tag key: extensions")
+	generateSwaggerCompliantCode  = flag.Bool("generate_swagger_compliant_code", false, "Whether to generate tag keys: swaggertype, enums. Also, keyed lists would be modeled as slices.")
+	generateJsonTags              = flag.Bool("generate_json_tags", false, "Whether to generate tag key: json")
+	generateExtensionTags         = flag.Bool("generate_extension_tags", false, "Whether to generate tag key: extensions")
+	addDescriptionsAsComments     = flag.Bool("descriptions_as_comments", false, "Add YANG descriptions as comments to generated code. Comments are added above struct fields and enclosed within opening tag (/*) and closing tag (*/).")
+	retainOnlyDeprecationComments = flag.Bool("retain_only_deprecation_comments", false, "Only comments starting with the string 'Deprecated' are retained. All others are dropped. This flag is meaningful only when YANG descriptions are added as comments.")
 )
 
 // writeGoCodeSingleFile takes a ygen.GeneratedGoCode struct and writes the Go code
@@ -365,6 +367,8 @@ func main() {
 				GenerateSwaggerCompliantCode:        *generateSwaggerCompliantCode,
 				GenerateJsonTags:                    *generateJsonTags,
 				GenerateExtensionTags:               *generateExtensionTags,
+				AddDescriptionsAsComments:           *addDescriptionsAsComments,
+				RetainOnlyDeprecationComments:       *retainOnlyDeprecationComments,
 			},
 		})
 

ygen/codegen.go

@@ -248,6 +248,12 @@ type GoOpts struct {
 	// The extension keyword and argument are comma-separated.
 	// Refer: https://datatracker.ietf.org/doc/html/rfc7950#section-7.19
 	GenerateExtensionTags bool
+	// AddDescriptionsAsComments adds YANG descriptions as comments to generated code. Comments
+	// are added above struct fields and enclosed within opening tag (/*) and closing tag (*/).
+	AddDescriptionsAsComments bool
+	// Only YANG descriptions starting with the string 'Deprecated' are added as comments.
+	// All others are dropped. This is meaningful only when used alongisde AddDescriptionsAsComments.
+	RetainOnlyDeprecationComments bool
 }
 
 // ProtoOpts stores Protobuf specific options for the code generation library.

ygen/gogen.go

@@ -45,6 +45,9 @@ const (
 	// annotationFieldType defines the type that should be used for the
 	// annotation/metadata fields within each struct when they are generated.
 	annotationFieldType string = "[]ygot.Annotation"
+	// deprecationCommentPrefix specifies the string that a YANG description
+	// must begin with to be considered a deprecation comment.
+	deprecationCommentPrefix string = "Deprecated"
 )
 
 // The methods in this file take the structs that have been generated by
@@ -188,8 +191,9 @@ type goEnumCodeSnippet struct {
 
 // goStructField contains a definition of a field within a Go struct.
 type goStructField struct {
-	Name string // Name is the field's name.
-	Type string // Type is the Go type of the field.
+	Name        string // Name is the field's name.
+	Type        string // Type is the Go type of the field.
+	Description string // Description is the YANG description.
 	// IsScalarField represents whether the element is a leaf, rather than a
 	// leaf-list or container. It is set to false explicitly where there are
 	// scalar types that are not mapped to pointers (particularly, enumerated
@@ -503,6 +507,9 @@ var ΓModelData = []*gpb.ModelData{
 // {{ .StructName }} represents the {{ .YANGPath }} YANG schema element.
 type {{ .StructName }} struct {
 {{- range $idx, $field := .Fields }}
+	{{- if $field.Description }}
+	/* {{ $field.Description }} */
+	{{- end }}
 	{{- if $field.IsScalarField }}
 	{{ $field.Name }}	*{{ $field.Type }}	`+"`"+`{{ $field.Tags }}`+"`"+`
 	{{- else }}
@@ -1701,6 +1708,16 @@ func writeGoStruct(targetStruct *Directory, goStructElements map[string]*Directo
 
 		fieldDef.Tags = tagBuf.String()
 
+		if goOpts.AddDescriptionsAsComments {
+			if goOpts.RetainOnlyDeprecationComments {
+				if strings.HasPrefix(field.Description, deprecationCommentPrefix) {
+					fieldDef.Description = field.Description
+				}
+			} else {
+				fieldDef.Description = field.Description
+			}
+		}
+
 		// Append the generated field definition to the set of fields of the struct.
 		structDef.Fields = append(structDef.Fields, fieldDef)