1/* 2Copyright 2019 The Kubernetes Authors. 3 4Licensed under the Apache License, Version 2.0 (the "License"); 5you may not use this file except in compliance with the License. 6You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10Unless required by applicable law or agreed to in writing, software 11distributed under the License is distributed on an "AS IS" BASIS, 12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13See the License for the specific language governing permissions and 14limitations under the License. 15*/ 16 17// Package markers contains utilities for defining and parsing "marker 18// comments", also occasionally called tag comments (we use the term marker to 19// avoid confusing with struct tags). Parsed result (output) values take the 20// form of Go values, much like the "encoding/json" package. 21// 22// Definitions and Parsing 23// 24// Markers are defined as structured Definitions which can be used to 25// consistently parse marker comments. A Definition contains an concrete 26// output type for the marker, which can be a simple type (like string), a 27// struct, or a wrapper type (useful for defining additional methods on marker 28// types). 29// 30// Markers take the general form 31// 32// +path:to:marker=val 33// 34// +path:to:marker:arg1=val,arg2=val2 35// 36// +path:to:marker 37// 38// Arguments may be ints, bools, strings, and slices. Ints and bool take their 39// standard form from Go. Strings may take any of their standard forms, or any 40// sequence of unquoted characters up until a `,` or `;` is encountered. Lists 41// take either of the following forms: 42// 43// val;val;val 44// 45// {val, val, val} 46// 47// Note that the first form will not properly parse nested slices, but is 48// generally convenient and is the form used in many existing markers. 49// 50// Each of those argument types maps to the corresponding go type. Pointers 51// mark optional fields (a struct tag, below, may also be used). The empty 52// interface will match any type. 53// 54// Struct fields may optionally be annotated with the `marker` struct tag. The 55// first argument is a name override. If it's left blank (or the tag isn't 56// present), the camelCase version of the name will be used. The only 57// additional argument defined is `optional`, which marks a field as optional 58// without using a pointer. 59// 60// All parsed values are unmarshalled into the output type. If any 61// non-optional fields aren't mentioned, an error will be raised unless 62// `Strict` is set to false. 63// 64// Registries and Lookup 65// 66// Definitions can be added to registries to facilitate lookups. Each 67// definition is marked as either describing a type, struct field, or package 68// (unassociated). The same marker name may be registered multiple times, as 69// long as each describes a different construct (type, field, or package). 70// Definitions can then be looked up by passing unparsed markers. 71// 72// Collection and Extraction 73// 74// Markers can be collected from a loader.Package using a Collector. The 75// Collector will read from a given Registry, collecting comments that look 76// like markers and parsing them if they match some definition on the registry. 77// 78// Markers are considered associated with a particular field or type if they 79// exist in the Godoc, or the closest non-godoc comment. Any other markers not 80// inside a some other block (e.g. a struct definition, interface definition, 81// etc) are considered package level. Markers in a "closest non-Go comment 82// block" may also be considered package level if registered as such and no 83// identical type-level definition exists. 84// 85// Like loader.Package, Collector's methods are idempotent and will not 86// reperform work. 87// 88// Traversal 89// 90// EachType function iterates over each type in a Package, providing 91// conveniently structured type and field information with marker values 92// associated. 93// 94// PackageMarkers can be used to fetch just package-level markers. 95// 96// Help 97// 98// Help can be defined for each marker using the DefinitionHelp struct. It's 99// mostly intended to be generated off of godocs using cmd/helpgen, which takes 100// the first line as summary (removing the type/field name), and considers the 101// rest as details. It looks for the 102// 103// +controllertools:generateHelp[:category=<string>] 104// 105// marker to start generation. 106// 107// If you can't use godoc-based generation for whatever reasons (e.g. 108// primitive-typed markers), you can use the SimpleHelp and DeprecatedHelp 109// helper functions to generate help structs. 110// 111// Help is then registered into a registry as associated with the actual 112// definition, and can then be later retrieved from the registry. 113package markers 114