From ced8d9597587c4ebf64f82305f5002bc39eefcf4 Mon Sep 17 00:00:00 2001 From: Mike Spreitzer Date: Tue, 7 Jul 2020 23:07:24 -0400 Subject: [PATCH] Fix description of conversion generator The old description failed to note that the Convert___To__ function is NOT generated if generation of the corresponding autoConvert_... function ran into trouble with a missing or mis-typed field. --- .../code-generator/cmd/conversion-gen/main.go | 40 ++++++++++++------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/staging/src/k8s.io/code-generator/cmd/conversion-gen/main.go b/staging/src/k8s.io/code-generator/cmd/conversion-gen/main.go index 09c45138238..6e0f31f068d 100644 --- a/staging/src/k8s.io/code-generator/cmd/conversion-gen/main.go +++ b/staging/src/k8s.io/code-generator/cmd/conversion-gen/main.go @@ -30,21 +30,33 @@ limitations under the License. // ones named // autoConvert___To__ // for each such pair of types --- both with (pkg1,pkg2) = -// (internal,external) and (pkg1,pkg2) = (external,internal). -// Additionally: if the destination package does not contain one in a -// non-generated file then a function named +// (internal,external) and (pkg1,pkg2) = (external,internal). The +// generated conversion functions recurse on the structure of the data +// types. For structs, source and destination fields are matched up +// according to name; if a source field has no corresponding +// destination or there is a fundamental mismatch in the type of the +// field then the generated autoConvert_... function has just a +// warning comment about that field. The generated conversion +// functions use standard value assignment wherever possible. For +// compound types, the generated conversion functions call the +// `Convert...` functions for the subsidiary types. +// +// For each pair of types `conversion-gen` will also generate a +// function named // Convert___To__ -// is also generated and it simply calls the `autoConvert...` -// function. The generated conversion functions use standard value -// assignment wherever possible. For compound types, the generated -// conversion functions call the `Convert...` functions for the -// subsidiary types. Thus developers can override the behavior for -// selected types. For a top-level object type (i.e., the type of an -// object that will be input to an apiserver), for such an override to -// be used by the apiserver the developer-maintained conversion -// functions must also be registered by invoking the -// `AddConversionFunc`/`AddGeneratedConversionFunc` method of the -// relevant `Scheme` object from k8s.io/apimachinery/pkg/runtime. +// if both of two conditions are met: (1) the destination package does +// not contain a function of that name in a non-generated file and (2) +// the generation of the corresponding autoConvert_... function did +// not run into trouble with a missing or fundamentally differently +// typed field. A generated Convert_... function simply calls the +// corresponding `autoConvert...` function. `conversion_gen` also +// generates a function that updates a given `runtime.Scheme` by +// registering all the Convert_... functions found and generated. +// Thus developers can override the generated behavior for selected +// type pairs by putting the desired Convert_... functions in +// non-generated files. Further, developers are practically required +// to override the generated behavior when there are missing or +// fundamentally differently typed fields. // // `conversion-gen` will scan its `--input-dirs`, looking at the // package defined in each of those directories for comment tags that