github.com/openshift/installer@v1.4.17/docs/dev/explain.md (about)

     1  # InstallConfig Explain
     2  
     3  The installer allows it's users to see all the configuration available using the `explain` subcommand. The command works almost like the
     4  the `oc explain` subcommand.
     5  
     6  ## Generating the documentation
     7  
     8  Like `oc explain` and Custom Resource Definitions, the installer also generates an internal only Custom Resource Definition for the `InstallConfig`.
     9  
    10  ```sh
    11  go generate ./pkg/types/installconfig.go
    12  ```
    13  
    14  The code generation uses the upstream project kubebuilder, which provides tools like controller-tools to [generate][kubebuilder-generate-crd] Custom Resource Definitions.
    15  
    16  ## Descriptions of fields and various types
    17  
    18  The generator uses the Godoc comments on the fields and types to create the descriptions. Therefore, making sure that everything used by the `InstallConfig` definition has user friendly comments will automatically transfer to user friendly explain output.
    19  
    20  ## Kubebuilder markers
    21  
    22  The generator allows use of various markers for fields and types to provide information about the valid inputs. Various available markers are defined [here][kubebuilder-validation-markers]
    23  
    24  ## Additional guidelines on godoc comments
    25  
    26  All definitions in installer codebase already follow and enforce [effective-go] guidelines, but for better explain output for the types these additional guidelines should also be followed
    27  
    28  1. No external types are allowed to be used in the `InstallConfig`. All the types used should be defined in the installer repository itself. The only exception is the `TypeMeta` and `ObjectMeta`.
    29  
    30  2. Fields should always have `json` tags that follow [mixedCaps][go-mixed-caps] and should always start with lowercase.
    31  
    32  3. The comments on the fields must use the `json` tag to reference the field.
    33  
    34  4. Optional fields must have the `+optional` marker defined. Optional fields must also define the default value. If the values are static, `+kubebuilder:validation=Default` marker should be used, otherwise the comment must clearly define how the default value will be calculated.
    35  
    36  5. Only string based enum types are allowed. Also such enum type must use `+kubebuilder:validation:Enum` marker.
    37  
    38  [go-effective]: https://golang.org/doc/effective_go.html
    39  [go-mixed-caps]: https://golang.org/doc/effective_go.html#mixed-caps
    40  [kubebuilder-generate-crd]: https://book.kubebuilder.io/reference/generating-crd.html
    41  [kubebuilder-validation-markers]: https://book.kubebuilder.io/reference/markers/crd-validation.html