github.com/alex123012/deckhouse-controller-tools@v0.0.0-20230510090815-d594daf1af8c/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  }