Add additional API type comments

Signed-off-by: James Munnelly <james@munnelly.eu>

pkg/apis/certmanager/v1alpha1/types_challenge.go

@@ -47,13 +47,30 @@ type ChallengeList struct {
 }
 
 type ChallengeSpec struct {
+	// AuthzURL is the URL to the ACME Authorization resource that this
+	// challenge is a part of.
 	AuthzURL string `json:"authzURL"`
-	Type     string `json:"type"`
-	URL      string `json:"url"`
-	DNSName  string `json:"dnsName"`
-	Token    string `json:"token"`
-	Key      string `json:"key"`
-	Wildcard bool   `json:"wildcard"`
+
+	// Type is the type of ACME challenge this resource represents, e.g. "dns01"
+	// or "http01"
+	Type string `json:"type"`
+
+	// URL is the URL of the ACME Challenge resource for this challenge.
+	// This can be used to lookup details about the status of this challenge.
+	URL string `json:"url"`
+
+	// DNSName is the identifier that this challenge is for, e.g. example.com.
+	DNSName string `json:"dnsName"`
+
+	// Token is the ACME challenge token for this challenge.
+	Token string `json:"token"`
+
+	// Key is the ACME challenge key for this challenge
+	Key string `json:"key"`
+
+	// Wildcard will be true if this challenge is for a wildcard identifier,
+	// for example '*.example.com'
+	Wildcard bool `json:"wildcard"`
 
 	// Config specifies the solver configuration for this challenge.
 	Config SolverConfig `json:"config"`
@@ -67,7 +84,19 @@ type ChallengeSpec struct {
 }
 
 type ChallengeStatus struct {
-	Presented bool   `json:"presented"`
-	Reason    string `json:"reason"`
-	State     State  `json:"state"`
+	// Presented will be set to true if the challenge values for this challenge
+	// are currently 'presented'.
+	// This *does not* imply the self check is passing. Only that the values
+	// have been 'submitted' for the appropriate challenge mechanism (i.e. the
+	// DNS01 TXT record has been presented, or the HTTP01 configuration has been
+	// configured).
+	Presented bool `json:"presented"`
+
+	// Reason contains human readable information on why the Challenge is in the
+	// current state.
+	Reason string `json:"reason"`
+
+	// State contains the current 'state' of the challenge.
+	// If not set, the state of the challenge is unknown.
+	State State `json:"state"`
 }

pkg/apis/certmanager/v1alpha1/types_order.go

@@ -164,21 +164,49 @@ const (
 	Expired State = "expired"
 )
 
+// SolverConfig is a container type holding the configuration for either a
+// HTTP01 or DNS01 challenge.
+// Only one of HTTP01 or DNS01 should be non-nil.
 type SolverConfig struct {
+	// HTTP01 contains HTTP01 challenge solving configuration
 	HTTP01 *HTTP01SolverConfig `json:"http01,omitempty"`
-	DNS01  *DNS01SolverConfig  `json:"dns01,omitempty"`
+
+	// DNS01 contains DNS01 challenge solving configuration
+	DNS01 *DNS01SolverConfig `json:"dns01,omitempty"`
 }
 
+// HTTP01SolverConfig contains solver configuration for HTTP01 challenges.
 type HTTP01SolverConfig struct {
-	Ingress      string  `json:"ingress"`
+	// Ingress is the name of an Ingress resource that will be edited to include
+	// the ACME HTTP01 'well-known' challenge path in order to solve HTTP01
+	// challenges.
+	// If this field is specified, 'ingressClass' **must not** be specified.
+	Ingress string `json:"ingress"`
+
+	// IngressClass is the ingress class that should be set on new ingress
+	// resources that are created in order to solve HTTP01 challenges.
+	// This field should be used when using an ingress controller such as nginx,
+	// which 'flattens' ingress configuration instead of maintaining a 1:1
+	// mapping between loadbalancer IP:ingress resources.
+	// If this field is not set, and 'ingress' is not set, then ingresses
+	// without an ingress class set will be created to solve HTTP01 challenges.
+	// If this field is specified, 'ingress' **must not** be specified.
 	IngressClass *string `json:"ingressClass,omitempty"`
 }
 
+// DNS01SolverConfig contains solver configuration for DNS01 challenges.
 type DNS01SolverConfig struct {
+	// Provider is the name of the DNS01 challenge provider to use, as configure
+	// on the referenced Issuer or ClusterIssuer resource.
 	Provider string `json:"provider"`
 }
 
+// DomainSolverConfig contains solver configuration for a set of domains.
 type DomainSolverConfig struct {
-	Domains      []string `json:"domains"`
+	// Domains is the list of domains that this SolverConfig applies to.
+	Domains []string `json:"domains"`
+
+	// SolverConfig contains the actual solver configuration to use for the
+	// provided set of domains.
 	SolverConfig `json:",inline"`
 }