github.com/matthchr/controller-tools@v0.3.1-0.20200602225425-d33ced351ff8/pkg/markers/help.go (about) 1 /* 2 Copyright 2019 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package markers 18 19 // You *probably* don't want to write these structs by hand 20 // -- use cmd/helpgen if you can write Godoc, and {Simple,Deprecated}Help 21 // otherwise. 22 23 // DetailedHelp contains brief help, as well as more details. 24 // For the "full" help, join the two together. 25 type DetailedHelp struct { 26 Summary string 27 Details string 28 } 29 30 // DefinitionHelp contains overall help for a marker Definition, 31 // as well as per-field help. 32 type DefinitionHelp struct { 33 // DetailedHelp contains the overall help for the marker. 34 DetailedHelp 35 // Category describes what kind of marker this is. 36 Category string 37 // DeprecatedInFavorOf marks the marker as deprecated. 38 // If non-nil & empty, it's assumed to just mean deprecated permanently. 39 // If non-empty, it's assumed to be a marker name. 40 DeprecatedInFavorOf *string 41 42 // NB(directxman12): we make FieldHelp be in terms of the Go struct field 43 // names so that we don't have to know the conversion or processing rules 44 // for struct fields at compile-time for help generation. 45 46 // FieldHelp defines the per-field help for this marker, *in terms of the 47 // go struct field names. Use the FieldsHelp method to map this to 48 // marker argument names. 49 FieldHelp map[string]DetailedHelp 50 } 51 52 // FieldsHelp maps per-field help to the actual marker argument names from the 53 // given definition. 54 func (d *DefinitionHelp) FieldsHelp(def *Definition) map[string]DetailedHelp { 55 fieldsHelp := make(map[string]DetailedHelp, len(def.FieldNames)) 56 for fieldName, argName := range def.FieldNames { 57 fieldsHelp[fieldName] = d.FieldHelp[argName] 58 } 59 return fieldsHelp 60 } 61 62 // SimpleHelp returns help that just has marker-level summary information 63 // (e.g. for use with empty or primitive-typed markers, where Godoc-based 64 // generation isn't possible). 65 func SimpleHelp(category, summary string) *DefinitionHelp { 66 return &DefinitionHelp{ 67 Category: category, 68 DetailedHelp: DetailedHelp{Summary: summary}, 69 } 70 } 71 72 // DeprecatedHelp returns simple help (a la SimpleHelp), except marked as 73 // deprecated in favor of the given marker (or an empty string for just 74 // deprecated). 75 func DeprecatedHelp(inFavorOf, category, summary string) *DefinitionHelp { 76 return &DefinitionHelp{ 77 Category: category, 78 DetailedHelp: DetailedHelp{Summary: summary}, 79 DeprecatedInFavorOf: &inFavorOf, 80 } 81 }