From 7f03dc5bfe52cec42b0763f4f82b7ea12cea0c0d Mon Sep 17 00:00:00 2001
From: Courtney Pacheco <cpacheco@redhat.com>
Date: Fri, 14 May 2021 13:49:25 -0400
Subject: [PATCH] Adding docs to NFD state funcs related to NFD itself (not
 just the operator)

Adding documentation to the NFD state functions related to NFD itself
so that users and contributors can understand how NFD works with the NFD
operator, especially if they are looking at another file that references
these functions and the NFD struct.
---
 controllers/nodefeaturediscovery_state.go | 34 ++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/controllers/nodefeaturediscovery_state.go b/controllers/nodefeaturediscovery_state.go
index c9184ac7..6b5cd427 100644
--- a/controllers/nodefeaturediscovery_state.go
+++ b/controllers/nodefeaturediscovery_state.go
@@ -22,21 +22,41 @@ import (
 	nfdv1 "github.com/kubernetes-sigs/node-feature-discovery-operator/api/v1"
 )
 
-// NFD holds the needed information to watch from the Controller
+// NFD holds the needed information to watch from the Controller. The
+// following descriptions elaborate on each field in this struct:
 type NFD struct {
+
+	// resources contains information about NFD's resources. For more
+	// information, see ./nodefeaturediscovery_resources.go
 	resources []Resources
+
+	// controls is a list that contains the status of an NFD resource
+	// as being Ready (=0) or NotReady (=1)
 	controls  []controlFunc
+
+	// rec represents the NFD reconciler struct used for reconciliation
 	rec       *NodeFeatureDiscoveryReconciler
+
+	// ins is the NodeFeatureDiscovery struct that contains the Schema
+	// for the nodefeaturediscoveries API
 	ins       *nfdv1.NodeFeatureDiscovery
+
+	// idx is the index that is used to step through the 'controls' list
+	// and is set to 0 upon calling 'init()'
 	idx       int
 }
 
+// addState takes a given path and finds resources in that path, then
+// appends a list of ctrl's functions to the NFD object's 'controls'
+// field and adds the list of resources found to 'n.resources'
 func (n *NFD) addState(path string) {
 	res, ctrl := addResourcesControls(path)
 	n.controls = append(n.controls, ctrl)
 	n.resources = append(n.resources, res)
 }
 
+// init initializes an NFD object by populating the fields before
+// attempting to run any kind of check.
 func (n *NFD) init(
 	r *NodeFeatureDiscoveryReconciler,
 	i *nfdv1.NodeFeatureDiscovery,
@@ -50,7 +70,17 @@ func (n *NFD) init(
 	}
 }
 
+// step steps through the list of functions stored in 'n.controls',
+// then attempts to determine if the given resource is Ready or
+// NotReady. (See the following file for a list of functions that
+// 'n.controls' can take on: ./nodefeaturediscovery_resources.go.)
 func (n *NFD) step() error {
+
+	// For each function in n.controls, attempt to check the status of
+	// the relevant resource. If no error occurs and the resource is
+	// defined as being "NotReady," then return an error saying it's not
+	// ready. Otherwise, return the status as being ready, then increment
+	// the index for n.controls so that we can parse the next resource.
 	for _, fs := range n.controls[n.idx] {
 		stat, err := fs(*n)
 		if err != nil {
@@ -64,6 +94,8 @@ func (n *NFD) step() error {
 	return nil
 }
 
+// last checks if the last index equals the number of functions
+// stored in n.controls.
 func (n *NFD) last() bool {
 	return n.idx == len(n.controls)
 }