Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add doc in types.go for hooks/description.sh #4680

Merged
merged 1 commit into from
Feb 20, 2015
Merged

Add doc in types.go for hooks/description.sh #4680

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
48 changes: 26 additions & 22 deletions pkg/api/v1beta1/types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ type GitRepo struct {
// Adapts a Secret into a VolumeSource
type SecretSource struct {
// Reference to a Secret
Target ObjectReference `json:"target"`
Target ObjectReference `json:"target" description:"target is a reference to a secret"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. We'll merge the PR to fix the Travis check right after we merge this PR so more of these don't get merged.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just "reference to a secret object"

}

// Port represents a network port in a single container
Expand Down Expand Up @@ -434,6 +434,7 @@ type ContainerStatus struct {
ContainerID string `json:"containerID,omitempty" description:"container's ID in the format 'docker://<container_id>'"`
}

// PodConditionKind is a valid value for PodCondition.Kind
type PodConditionKind string

// These are valid conditions of pod.
Expand All @@ -445,8 +446,10 @@ const (

// TODO: add LastTransitionTime, Reason, Message to match NodeCondition api.
type PodCondition struct {
Kind PodConditionKind `json:"kind" description:"kind of the condition, currently only Ready"`
Status ConditionStatus `json:"status" description:"status of the condition, one of Full, None, Unknown"`
// Kind is the kind of the condition
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need the comments, since we have the descriptions?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just added for consistency.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, though I don't think we're very consistent about it, and it just creates 2 things to update and keep in sync.

Kind PodConditionKind `json:"kind" description:"kind of the condition, currently only Ready"`
// Status is the status of the condition
Status ConditionStatus `json:"status" description:"status of the condition, one of Full, None, Unknown"`
}

// PodInfo contains one entry for every container with available info.
Expand Down Expand Up @@ -710,17 +713,18 @@ type Namespace struct {
Labels map[string]string `json:"labels,omitempty" description:"map of string keys and values that can be used to organize and categorize namespaces"`

// Spec defines the behavior of the Namespace.
Spec NamespaceSpec `json:"spec,omitempty"`
Spec NamespaceSpec `json:"spec,omitempty" description:"spec defines the behavior of the Namespace"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I usually put specification of the desired state of the Foo, but what you have is fine.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Except that I'd eliminate the field name from the description.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have a ton more time to refine this today, so if the goal is to enable the script to not allow more deviation, then this should be good to go. We can nit text later I guess.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, fine.


// Status describes the current status of a Namespace
Status NamespaceStatus `json:"status,omitempty"`
Status NamespaceStatus `json:"status,omitempty" description:"status describes the current status of a Namespace"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would omit "status describes"

}

// NamespaceList is a list of Namespaces.
type NamespaceList struct {
TypeMeta `json:",inline"`

Items []Namespace `json:"items"`
// Items is the list of Namespace objects in the list
Items []Namespace `json:"items" description:"items is the list of Namespace objects in the list"`
}

// Binding is written by a scheduler to cause a pod to be bound to a host.
Expand Down Expand Up @@ -1017,33 +1021,33 @@ const (
// LimitRangeItem defines a min/max usage limit for any resource that matches on kind
type LimitRangeItem struct {
// Type of resource that this limit applies to
Type LimitType `json:"type,omitempty"`
Type LimitType `json:"type,omitempty" description:"type of resource that this limit applies to"`
// Max usage constraints on this kind by resource name
Max ResourceList `json:"max,omitempty"`
Max ResourceList `json:"max,omitempty" description:"max usage constraints on this kind by resource name"`
// Min usage constraints on this kind by resource name
Min ResourceList `json:"min,omitempty"`
Min ResourceList `json:"min,omitempty" description:"min usage constraints on this kind by resource name"`
}

// LimitRangeSpec defines a min/max usage limit for resources that match on kind
type LimitRangeSpec struct {
// Limits is the list of LimitRangeItem objects that are enforced
Limits []LimitRangeItem `json:"limits"`
Limits []LimitRangeItem `json:"limits" description:"limits is the list of LimitRangeItem objects that are enforced"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Omit "limits is the".

}

// LimitRange sets resource usage limits for each kind of resource in a Namespace
type LimitRange struct {
TypeMeta `json:",inline"`

// Spec defines the limits enforced
Spec LimitRangeSpec `json:"spec,omitempty"`
Spec LimitRangeSpec `json:"spec,omitempty" description:"spec defines the limits enforced"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "resource limits enforced"

}

// LimitRangeList is a list of LimitRange items.
type LimitRangeList struct {
TypeMeta `json:",inline"`

// Items is a list of LimitRange objects
Items []LimitRange `json:"items"`
Items []LimitRange `json:"items" description:"items is a list of LimitRange objects"`
}

// The following identify resource constants for Kubernetes object types
Expand All @@ -1061,26 +1065,26 @@ const (
// ResourceQuotaSpec defines the desired hard limits to enforce for Quota
type ResourceQuotaSpec struct {
// Hard is the set of desired hard limits for each named resource
Hard ResourceList `json:"hard,omitempty"`
Hard ResourceList `json:"hard,omitempty" description:"hard is the set of desired hard limits for each named resource"`
}

// ResourceQuotaStatus defines the enforced hard limits and observed use
type ResourceQuotaStatus struct {
// Hard is the set of enforced hard limits for each named resource
Hard ResourceList `json:"hard,omitempty"`
Hard ResourceList `json:"hard,omitempty" description:"hard is the set of enforced hard limits for each named resource"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Omit "hard is the"

// Used is the current observed total usage of the resource in the namespace
Used ResourceList `json:"used,omitempty"`
Used ResourceList `json:"used,omitempty" description:"used is the current observed total usage of the resource in the namespace"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Omit "used is the"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anyway, you get the idea. Omit the field name, "is", and "the".

"Defines"/"specifies" and "describes" might sometimes be appropriate to distinguish spec and status, but might not always be necessary.

}

// ResourceQuota sets aggregate quota restrictions enforced per namespace
type ResourceQuota struct {
TypeMeta `json:",inline"`

// Spec defines the desired quota
Spec ResourceQuotaSpec `json:"spec,omitempty"`
Spec ResourceQuotaSpec `json:"spec,omitempty" description:"spec defines the desired quota"`

// Status defines the actual enforced quota and its current usage
Status ResourceQuotaStatus `json:"status,omitempty"`
Status ResourceQuotaStatus `json:"status,omitempty" description:"status defines the actual enforced quota and current usage"`
}

// ResourceQuotaUsage captures system observed quota status per namespace
Expand All @@ -1089,15 +1093,15 @@ type ResourceQuotaUsage struct {
TypeMeta `json:",inline"`

// Status defines the actual enforced quota and its current usage
Status ResourceQuotaStatus `json:"status,omitempty"`
Status ResourceQuotaStatus `json:"status,omitempty" description:"status defines the actual enforced quota and current usage"`
}

// ResourceQuotaList is a list of ResourceQuota items
type ResourceQuotaList struct {
TypeMeta `json:",inline"`

// Items is a list of ResourceQuota objects
Items []ResourceQuota `json:"items"`
Items []ResourceQuota `json:"items" description:"items is a list of ResourceQuota objects"`
}

// Secret holds secret data of a certain type. The total bytes of the values in
Expand All @@ -1107,10 +1111,10 @@ type Secret struct {

// Data contains the secret data. Each key must be a valid DNS_SUBDOMAIN.
// The serialized form of the secret data is a base64 encoded string.
Data map[string][]byte `json:"data,omitempty"`
Data map[string][]byte `json:"data,omitempty" description:"data contains the secret data. Each key must be a valid DNS_SUBDOMAIN. Each value must be a base64 encoded string"`

// Used to facilitate programatic handling of secret data.
Type SecretType `json:"type,omitempty"`
Type SecretType `json:"type,omitempty" description:"type facilitates programmatic handling of secret data"`
}

const MaxSecretSize = 1 * 1024 * 1024
Expand All @@ -1124,5 +1128,5 @@ const (
type SecretList struct {
TypeMeta `json:",inline"`

Items []Secret `json:"items"`
Items []Secret `json:"items" description:"items is a list of secret objects"`
}
50 changes: 27 additions & 23 deletions pkg/api/v1beta2/types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ type EmptyDir struct{}
// Adapts a Secret into a VolumeSource
type SecretSource struct {
// Reference to a Secret
Target ObjectReference `json:"target"`
Target ObjectReference `json:"target" description:"target is a reference to a secret"`
}

// Protocol defines network protocols supported for things like conatiner ports.
Expand Down Expand Up @@ -398,6 +398,7 @@ type ContainerStatus struct {
ContainerID string `json:"containerID,omitempty" description:"container's ID in the format 'docker://<container_id>'"`
}

// PodConditionKind is a valid value for PodCondition.Kind
type PodConditionKind string

// These are valid conditions of pod.
Expand All @@ -409,8 +410,10 @@ const (

// TODO: add LastTransitionTime, Reason, Message to match NodeCondition api.
type PodCondition struct {
Kind PodConditionKind `json:"kind" description:"kind of the condition, currently only Ready"`
Status ConditionStatus `json:"status" description:"status of the condition, one of Full, None, Unknown"`
// Kind is the kind of the condition
Kind PodConditionKind `json:"kind" description:"kind of the condition, currently only Ready"`
// Status is the status of the condition
Status ConditionStatus `json:"status" description:"status of the condition, one of Full, None, Unknown"`
}

// PodInfo contains one entry for every container with available info.
Expand Down Expand Up @@ -671,17 +674,18 @@ type Namespace struct {
Labels map[string]string `json:"labels,omitempty" description:"map of string keys and values that can be used to organize and categorize namespaces"`

// Spec defines the behavior of the Namespace.
Spec NamespaceSpec `json:"spec,omitempty"`
Spec NamespaceSpec `json:"spec,omitempty" description:"spec defines the behavior of the Namespace"`

// Status describes the current status of a Namespace
Status NamespaceStatus `json:"status,omitempty"`
Status NamespaceStatus `json:"status,omitempty" description:"status describes the current status of a Namespace"`
}

// NamespaceList is a list of Namespaces.
type NamespaceList struct {
TypeMeta `json:",inline"`

Items []Namespace `json:"items"`
// Items is the list of Namespace objects in the list
Items []Namespace `json:"items" description:"items is the list of Namespace objects in the list"`
}

// Binding is written by a scheduler to cause a pod to be bound to a host.
Expand Down Expand Up @@ -1020,33 +1024,33 @@ const (
// LimitRangeItem defines a min/max usage limit for any resource that matches on kind
type LimitRangeItem struct {
// Type of resource that this limit applies to
Type LimitType `json:"type,omitempty"`
Type LimitType `json:"type,omitempty" description:"type of resource that this limit applies to"`
// Max usage constraints on this kind by resource name
Max ResourceList `json:"max,omitempty"`
Max ResourceList `json:"max,omitempty" description:"max usage constraints on this kind by resource name"`
// Min usage constraints on this kind by resource name
Min ResourceList `json:"min,omitempty"`
Min ResourceList `json:"min,omitempty" description:"min usage constraints on this kind by resource name"`
}

// LimitRangeSpec defines a min/max usage limit for resources that match on kind
type LimitRangeSpec struct {
// Limits is the list of LimitRangeItem objects that are enforced
Limits []LimitRangeItem `json:"limits"`
Limits []LimitRangeItem `json:"limits" description:"limits is the list of LimitRangeItem objects that are enforced"`
}

// LimitRange sets resource usage limits for each kind of resource in a Namespace
type LimitRange struct {
TypeMeta `json:",inline"`

// Spec defines the limits enforced
Spec LimitRangeSpec `json:"spec,omitempty"`
Spec LimitRangeSpec `json:"spec,omitempty" description:"spec defines the limits enforced"`
}

// LimitRangeList is a list of LimitRange items.
type LimitRangeList struct {
TypeMeta `json:",inline"`

// Items is a list of LimitRange objects
Items []LimitRange `json:"items"`
Items []LimitRange `json:"items" description:"items is a list of LimitRange objects"`
}

// The following identify resource constants for Kubernetes object types
Expand All @@ -1064,26 +1068,26 @@ const (
// ResourceQuotaSpec defines the desired hard limits to enforce for Quota
type ResourceQuotaSpec struct {
// Hard is the set of desired hard limits for each named resource
Hard ResourceList `json:"hard,omitempty"`
Hard ResourceList `json:"hard,omitempty" description:"hard is the set of desired hard limits for each named resource"`
}

// ResourceQuotaStatus defines the enforced hard limits and observed use
type ResourceQuotaStatus struct {
// Hard is the set of enforced hard limits for each named resource
Hard ResourceList `json:"hard,omitempty"`
Hard ResourceList `json:"hard,omitempty" description:"hard is the set of enforced hard limits for each named resource"`
// Used is the current observed total usage of the resource in the namespace
Used ResourceList `json:"used,omitempty"`
Used ResourceList `json:"used,omitempty" description:"used is the current observed total usage of the resource in the namespace"`
}

// ResourceQuota sets aggregate quota restrictions enforced per namespace
type ResourceQuota struct {
TypeMeta `json:",inline"`

// Spec defines the desired quota
Spec ResourceQuotaSpec `json:"spec,omitempty"`
Spec ResourceQuotaSpec `json:"spec,omitempty" description:"spec defines the desired quota"`

// Status defines the actual enforced quota and its current usage
Status ResourceQuotaStatus `json:"status,omitempty"`
Status ResourceQuotaStatus `json:"status,omitempty" description:"status defines the actual enforced quota and current usage"`
}

// ResourceQuotaUsage captures system observed quota status per namespace
Expand All @@ -1092,15 +1096,15 @@ type ResourceQuotaUsage struct {
TypeMeta `json:",inline"`

// Status defines the actual enforced quota and its current usage
Status ResourceQuotaStatus `json:"status,omitempty"`
Status ResourceQuotaStatus `json:"status,omitempty" description:"status defines the actual enforced quota and current usage"`
}

// ResourceQuotaList is a list of ResourceQuota items
type ResourceQuotaList struct {
TypeMeta `json:",inline"`

// Items is a list of ResourceQuota objects
Items []ResourceQuota `json:"items"`
Items []ResourceQuota `json:"items" description:"items is a list of ResourceQuota objects"`
}

// Secret holds secret data of a certain type. The total bytes of the values in
Expand All @@ -1109,11 +1113,11 @@ type Secret struct {
TypeMeta `json:",inline"`

// Data contains the secret data. Each key must be a valid DNS_SUBDOMAIN.
Data map[string][]byte `json:"data,omitempty"`
// The serialized form of the secret data is a base64 encoded string.
Data map[string][]byte `json:"data,omitempty" description:"data contains the secret data. Each key must be a valid DNS_SUBDOMAIN. Each value must be a base64 encoded string"`

// Used to facilitate programatic handling of secret data.
// The serialized form of the secret data is a base64 encoded string.
Type SecretType `json:"type,omitempty"`
Type SecretType `json:"type,omitempty" description:"type facilitates programmatic handling of secret data"`
}

const MaxSecretSize = 1 * 1024 * 1024
Expand All @@ -1127,5 +1131,5 @@ const (
type SecretList struct {
TypeMeta `json:",inline"`

Items []Secret `json:"items"`
Items []Secret `json:"items" description:"items is a list of secret objects"`
}