From 4982cbb2d8ab4330a871c59567e81269a96d1312 Mon Sep 17 00:00:00 2001 From: Mike Spreitzer Date: Thu, 6 Dec 2018 18:06:05 -0500 Subject: [PATCH] Update doc for k8s.io/code-generator/cmd/conversion-gen Added explanation of the `k8s:conversion-gen-external-types` comment tag. Added explanation of how the developer can selectively override the generated conversion functions. Also updated description in Makefile.generated_files. --- build/root/Makefile.generated_files | 23 ++++--- .../code-generator/cmd/conversion-gen/main.go | 63 +++++++++++++++---- 2 files changed, 66 insertions(+), 20 deletions(-) diff --git a/build/root/Makefile.generated_files b/build/root/Makefile.generated_files index 54f8d918de..3c4327ad61 100644 --- a/build/root/Makefile.generated_files +++ b/build/root/Makefile.generated_files @@ -296,16 +296,23 @@ $(DEFAULTER_GEN): $(k8s.io/kubernetes/vendor/k8s.io/code-generator/cmd/defaulter # Conversion generation + +# Any package that wants conversion functions generated into it must +# include one or more comment-tags in its `doc.go` file, of the form: +# // +k8s:conversion-gen= # -# Any package that wants conversion functions generated must include one or -# more comment-tags in any .go file, in column 0, of the form: -# // +k8s:conversion-gen= +# The INTERNAL_TYPES_DIR is a project-local path to another directory +# which should be considered when evaluating peer types for +# conversions. An optional additional comment of the form +# // +k8s:conversion-gen-external-types= # -# The CONVERSION_TARGET_DIR is a project-local path to another directory which -# should be considered when evaluating peer types for conversions. Types which -# are found in the source package (where conversions are being generated) -# but do not have a peer in one of the target directories will not have -# conversions generated. +# identifies where to find the external types; if there is no such +# comment then the external types are sought in the package where the +# `k8s:conversion` tag is found. +# +# Conversions, in both directions, are generated for every type name +# that is defined in both an internal types package and the external +# types package. # # TODO: it might be better in the long term to make peer-types explicit in the # IDL. 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 698baa7db7..215b17bdee 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 @@ -14,20 +14,59 @@ See the License for the specific language governing permissions and limitations under the License. */ -// conversion-gen is a tool for auto-generating Conversion functions. +// conversion-gen is a tool for auto-generating functions that convert +// between internal and external types. A general conversion code +// generation task involves three sets of packages: (1) a set of +// packages containing internal types, (2) a single package containing +// the external types, and (3) a single destination package (i.e., +// where the generated conversion functions go, and where the +// developer-authored conversion functions are). The packages +// containing the internal types play the role known as "peer +// packages" in the general code-generation framework of Kubernetes. // -// Given a list of input directories, it will scan for "peer" packages and -// generate functions that efficiently convert between same-name types in each -// package. For any pair of types that has a -// `Convert___To____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 +// 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 +// `AddConversionFuncs` method of the relevant `Scheme` object from +// k8s.io/apimachinery/pkg/runtime. // -// Generation is governed by comment tags in the source. Any package may -// request Conversion generation by including a comment in the file-comments of -// one file, of the form: -// // +k8s:conversion-gen= +// `conversion-gen` will scan its `--input-dirs`, looking at the +// package defined in each of those directories for comment tags that +// define a conversion code generation task. A package requests +// conversion code generation by including one or more comment in the +// package's `doc.go` file (currently anywhere in that file is +// acceptable, but the recommended location is above the `package` +// statement), of the form: +// // +k8s:conversion-gen= +// This introduces a conversion task, for which the destination +// package is the one containing the file with the tag and the tag +// identifies a package containing internal types. If there is also a +// tag of the form +// // +k8s:conversion-gen-external-types= +// then it identifies the package containing the external types; +// otherwise they are in the destination package. +// +// For each conversion code generation task, the full set of internal +// packages (AKA peer packages) consists of the ones specified in the +// `k8s:conversion-gen` tags PLUS any specified in the +// `--base-peer-dirs` and `--extra-peer-dirs` flags on the command +// line. // // When generating for a package, individual types or fields of structs may opt // out of Conversion generation by specifying a comment on the of the form: