Add or modify comments for multiple methods (fluid-cloudnative#247)

* Add some comments for utils

* Add some comments for ddc/alluxio

pkg/ddc/alluxio/operations/base.go

@@ -225,7 +225,7 @@ func (a AlluxioFileUtils) IsMounted(alluxioPath string) (mounted bool, err error
 	return mounted, err
 }
 
-// Check if it's ready
+// Check if the Alluxio is ready by running `alluxio fsadmin report` command
 func (a AlluxioFileUtils) Ready() (ready bool) {
 	var (
 		command = []string{"alluxio", "fsadmin", "report"}

pkg/ddc/alluxio/operations/cached.go

@@ -58,6 +58,7 @@ func (a AlluxioFileUtils) CachedState() (cached int64, err error) {
 	return
 }
 
+// clean cache with a preset timeout of 60s
 func (a AlluxioFileUtils) CleanCache(path string) (err error) {
 	var (
 		command = []string{"timeout", "-t", "60", "alluxio", "fs", "free", "-f", path}

pkg/ddc/alluxio/operations/local.go

@@ -20,6 +20,11 @@ import (
 	"time"
 )
 
+/*
+* Sync local path by running command `du -sh <path>`.
+* Under the circumstance where some NAS(e.g. NFS) is mounted on the `<path>`, the function will sync metadata of all files in the NAS.
+* This is necessary for Alluxio to get consistent file metadata with UFS(i.e. NAS in this case).
+ */
 func (a AlluxioFileUtils) SyncLocalDir(path string) (err error) {
 	var (
 		// command = []string{"alluxio", "fs", "-Dalluxio.user.file.metadata.sync.interval=0", "ls", "-R", alluxioPath}

pkg/ddc/alluxio/shutdown.go

@@ -27,6 +27,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
+// shut down the Alluxio engine
 func (e *AlluxioEngine) Shutdown() (err error) {
 	if e.retryShutdown < e.gracefulShutdownLimits {
 		err = e.cleanupCache()

pkg/ddc/alluxio/status.go

@@ -24,7 +24,7 @@ import (
 	"k8s.io/client-go/util/retry"
 )
 
-// init the status of the engine when it's ready
+// Check the related runtime status and update it
 func (e *AlluxioEngine) CheckAndUpdateRuntimeStatus() (ready bool, err error) {
 
 	var (

pkg/ddc/alluxio/ufs.go

@@ -19,19 +19,25 @@ import (
 	"github.com/fluid-cloudnative/fluid/pkg/ddc/alluxio/operations"
 )
 
+// return used storage size of Alluxio in bytes
 func (e *AlluxioEngine) UsedStorageBytes() (value int64, err error) {
 	// return e.usedStorageBytesInternal()
 	return e.usedStorageBytesInternal()
 }
 
+// return free storage size of Alluxio in bytes
 func (e *AlluxioEngine) FreeStorageBytes() (value int64, err error) {
 	// return e.freeStorageBytesInternal()
 	return e.freeStorageBytesInternal()
 }
+
+// return total storage size of Alluxio in bytes
 func (e *AlluxioEngine) TotalStorageBytes() (value int64, err error) {
 	// return e.totalStorageBytesInternal()
 	return e.totalStorageBytesInternal()
 }
+
+// return the total num of files in Alluxio
 func (e *AlluxioEngine) TotalFileNums() (value int64, err error) {
 	// return e.totalFileNumsInternal()
 	return e.totalFileNumsInternal()

pkg/utils/byte_size.go

@@ -33,6 +33,8 @@ func BytesSize(size float64) string {
 	return units.CustomSize("%.2f%s", size, 1024.0, binaryAbbrs)
 }
 
+// FromHumanSize returns an integer from a human-readable specification of a
+// size with 1024 as multiplier (eg. "44kB" = "(44 * 1024)B").
 func FromHumanSize(size string) (int64, error) {
 	return parseSize(size, binaryMap)
 }

pkg/utils/crtl_utils.go

@@ -31,19 +31,22 @@ func IgnoreNotFound(err error) error {
 	return err
 }
 
-// No requeue
+// NoRequeue returns the result of a reconciler invocation and won't requeue.
 func NoRequeue() (ctrl.Result, error) {
 	return RequeueIfError(nil)
 }
 
+// RequeueAfterInterval returns the result of a reconciler invocation with a given requeue interval.
 func RequeueAfterInterval(interval time.Duration) (ctrl.Result, error) {
 	return ctrl.Result{RequeueAfter: interval}, nil
 }
 
+// RequeueImmediately returns the result of a reconciler invocation and requeue immediately.
 func RequeueImmediately() (ctrl.Result, error) {
 	return ctrl.Result{Requeue: true}, nil
 }
 
+// RequeueIfError returns the result of a reconciler invocation and requeue immediately if err is not nil.
 func RequeueIfError(err error) (ctrl.Result, error) {
 	return ctrl.Result{}, err
 }

pkg/utils/dataset_condition.go

@@ -57,6 +57,8 @@ func UpdateDatasetCondition(conditions []datav1alpha1.DatasetCondition, conditio
 	return conditions
 }
 
+// get dataset condition given a dataset condition type.
+// If found, return index of the founded condition in the condition array and the founded condition itself, otherwise return -1 and nil.
 func GetDatasetCondition(conditions []datav1alpha1.DatasetCondition,
 	condType datav1alpha1.DatasetConditionType) (index int, condition *datav1alpha1.DatasetCondition) {
 
@@ -84,6 +86,7 @@ func GetDatasetCondition(conditions []datav1alpha1.DatasetCondition,
 // 	return newConditions
 // }
 
+// Check if the given dataset condition exists in the given dataset condition array.
 func IsDatasetConditionExist(conditions []datav1alpha1.DatasetCondition,
 	cond datav1alpha1.DatasetCondition) (found bool) {
 

pkg/utils/helm/helm.go

@@ -158,6 +158,7 @@ func GetChartVersion(chart string) (version string, err error) {
 	return version, nil
 }
 
+// GetChartName extracts the last element of the chart's path as the chart's name
 func GetChartName(chart string) string {
 	return filepath.Base(chart)
 }

pkg/utils/kubeclient/configmap.go

@@ -25,6 +25,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
+// Check if the configMap exists given its name and namespace
 func IsConfigMapExist(client client.Client, name, namespace string) (found bool, err error) {
 	key := types.NamespacedName{
 		Name:      name,
@@ -44,6 +45,7 @@ func IsConfigMapExist(client client.Client, name, namespace string) (found bool,
 	return found, err
 }
 
+// Delete the configmap given its name and namespace if the configmap exists
 func DeleteConfigMap(client client.Client, name, namespace string) (err error) {
 	key := types.NamespacedName{
 		Name:      name,

pkg/utils/kubeclient/exec.go

@@ -146,14 +146,17 @@ func ExecCommandInContainerWithFullOutput(podName string, containerName string,
 	})
 }
 
+// Execute shell command or script in the specified container and return stdout, stderr and error
 func ExecShellInContainer(podName string, containerName string, namespace string, cmd string) (stdout string, stderr string, err error) {
 	return ExecCommandInContainer(podName, containerName, namespace, []string{"/bin/sh", "-c", cmd})
 }
 
+// A wrapper function of ExecCommandInContainerWithFullOutput
 func ExecCommandInContainer(podName string, containerName string, namespace string, cmd []string) (stdout string, stderr string, err error) {
 	return ExecCommandInContainerWithFullOutput(podName, containerName, namespace, cmd)
 }
 
+// Find the first container in the given pod, executes command in that container, and return stdout, stderr and error.
 func ExecCommandInPod(podName string, namespace string, cmd []string) (stdout string, stderr string, err error) {
 	pod, err := clientset.CoreV1().Pods(namespace).Get(context.TODO(), podName, metav1.GetOptions{})
 	if err != nil {

pkg/utils/kubeclient/namespace.go

@@ -37,8 +37,6 @@ func EnsureNamespace(client client.Client, namespace string) (err error) {
 	if err = client.Get(context.TODO(), key, &ns); err != nil {
 		if apierrs.IsNotFound(err) {
 			return createNamespace(client, namespace)
-		} else {
-			return err
 		}
 	}
 	return err

pkg/utils/kubeclient/pod.go

@@ -45,6 +45,7 @@ func IsFailedPod(pod *corev1.Pod) bool {
 	return pod != nil && pod.Status.Phase == corev1.PodFailed
 }
 
+// get pod given name and namespace of the pod.
 func GetPodByName(client client.Client, name, namespace string) (pod *corev1.Pod, err error) {
 	key := types.NamespacedName{
 		Name:      name,
@@ -64,6 +65,7 @@ func GetPodByName(client client.Client, name, namespace string) (pod *corev1.Pod
 	return
 }
 
+// delete the given pod if it exists
 func DeletePod(client client.Client, pod *corev1.Pod) error {
 	err := client.Delete(context.TODO(), pod)
 	if apierrs.IsNotFound(err) {

pkg/utils/kubeclient/volume.go

@@ -31,7 +31,7 @@ const (
 	persistentVolumeClaimProtectionFinalizerName = "kubernetes.io/pvc-protection"
 )
 
-// IsPersistentVolumeExist
+// IsPersistentVolumeExist checks if the persistent volume exists given name and annotations of the PV.
 func IsPersistentVolumeExist(client client.Client, name string, annotations map[string]string) (found bool, err error) {
 	key := types.NamespacedName{
 		Name: name,
@@ -66,7 +66,7 @@ func IsPersistentVolumeExist(client client.Client, name string, annotations map[
 	return found, err
 }
 
-// IsPersistentVolumeClaimExist
+// IsPersistentVolumeClaimExist checks if the persistent volume claim exists given name, namespace and annotations of the PVC.
 func IsPersistentVolumeClaimExist(client client.Client, name, namespace string, annotations map[string]string) (found bool, err error) {
 	key := types.NamespacedName{
 		Name:      name,

pkg/utils/mount.go

@@ -19,6 +19,7 @@ import "os"
 
 const MountRoot string = "MOUNT_ROOT"
 
+//GetMountRoot gets the value of the env variable named MOUNT_ROOT
 func GetMountRoot() string {
 	return os.Getenv(MountRoot)
 }

pkg/utils/runtime_condition.go

@@ -34,7 +34,7 @@ func NewRuntimeCondition(conditionType data.RuntimeConditionType, reason, messag
 	}
 }
 
-// SetDatasetCondition updates the dataset to include the provided condition.
+// UpdateRuntimeCondition updates the runtime to include the provided condition.
 // If the condition that we are about to add already exists
 // and has the same status and reason then we are not going to update.
 func UpdateRuntimeCondition(conditions []data.RuntimeCondition, condition data.RuntimeCondition) []data.RuntimeCondition {
@@ -56,6 +56,8 @@ func UpdateRuntimeCondition(conditions []data.RuntimeCondition, condition data.R
 	return conditions
 }
 
+// get runtime condition given a runtime condition type.
+// If found, return index of the founded condition in the condition array and the founded condition itself, otherwise return -1 and nil.
 func GetRuntimeCondition(conditions []data.RuntimeCondition,
 	condType data.RuntimeConditionType) (index int, condition *data.RuntimeCondition) {
 	if conditions == nil {