Add documentation

ccUnitMeasure.go

@@ -22,6 +22,7 @@ const (
 	Events
 )
 
+// String returns the long string for the measure like 'Percent' or 'Seconds'
 func (m *Measure) String() string {
 	switch *m {
 	case Bytes:
@@ -59,6 +60,7 @@ func (m *Measure) String() string {
 	}
 }
 
+// Short returns the short string for the measure like 'B' (Bytes), 's' (Time) or 'W' (Watt). Is is recommened to use Short() over String().
 func (m *Measure) Short() string {
 	switch *m {
 	case Bytes:
@@ -126,6 +128,8 @@ var requestsRegex = regexp.MustCompile(requestsRegexStr)
 var packetsRegex = regexp.MustCompile(packetsRegexStr)
 var eventsRegex = regexp.MustCompile(eventsRegexStr)
 
+// NewMeasure creates a new measure out of a string representing a measure like 'Bytes', 'Flops' and 'precent'.
+// It uses regular expressions for matching.
 func NewMeasure(unit string) Measure {
 	var match []string
 	match = bytesRegex.FindStringSubmatch(unit)

ccUnitPrefix.go

@@ -31,6 +31,7 @@ const prefixRegexStr = `^([kKmMgGtTpP]?[i]?)(.*)`
 
 var prefixRegex = regexp.MustCompile(prefixRegexStr)
 
+// String returns the long string for the prefix like 'Kilo' or 'Mega'
 func (s *Prefix) String() string {
 	switch *s {
 	case InvalidPrefix:
@@ -72,6 +73,7 @@ func (s *Prefix) String() string {
 	}
 }
 
+// Prefix returns the short string for the prefix like 'K', 'M' or 'G'. Is is recommened to use Prefix() over String().
 func (s *Prefix) Prefix() string {
 	switch *s {
 	case InvalidPrefix:
@@ -113,6 +115,7 @@ func (s *Prefix) Prefix() string {
 	}
 }
 
+// NewPrefix creates a new prefix out of a string representing a unit like 'k', 'K', 'M' or 'G'.
 func NewPrefix(prefix string) Prefix {
 	switch prefix {
 	case "k":

ccUnits.go

@@ -24,12 +24,12 @@ type Unit interface {
 
 var INVALID_UNIT = NewUnit("foobar")
 
-// Check whether a unit is a valid unit. It requires at least a prefix and a measure. The unit denominator is optional
+// Valid checks whether a unit is a valid unit. A unit is valid if it has at least a prefix and a measure. The unit denominator is optional.
 func (u *unit) Valid() bool {
 	return u.prefix != InvalidPrefix && u.measure != InvalidMeasure
 }
 
-// Get the long string for the unit like 'KiloHertz'
+// String returns the long string for the unit like 'KiloHertz' or 'MegaBytes'
 func (u *unit) String() string {
 	if u.divMeasure != InvalidMeasure {
 		return fmt.Sprintf("%s%s/%s", u.prefix.String(), u.measure.String(), u.divMeasure.String())
@@ -38,7 +38,7 @@ func (u *unit) String() string {
 	}
 }
 
-// Get the short string for the unit like 'KHz' (recommened over String()!)
+// Short returns the short string for the unit like 'kHz' or 'MByte'. Is is recommened to use Short() over String().
 func (u *unit) Short() string {
 	if u.divMeasure != InvalidMeasure {
 		return fmt.Sprintf("%s%s/%s", u.prefix.Prefix(), u.measure.Short(), u.divMeasure.Short())
@@ -47,7 +47,9 @@ func (u *unit) Short() string {
 	}
 }
 
-//
+// AddUnitDenominator adds a unit denominator to an exising unit. Can be used if you want to derive e.g. data volume to bandwidths.
+// The data volume is in a Byte unit like 'kByte' and by dividing it by the runtime in seconds, we get the bandwidth. We can use the
+// data volume unit and add 'Second' as unit denominator
 func (u *unit) AddUnitDenominator(div Measure) {
 	u.divMeasure = div
 }
@@ -68,7 +70,8 @@ func (u *unit) getUnitDenominator() Measure {
 	return u.divMeasure
 }
 
-// This creates the default conversion function between two prefixes
+// GetPrefixPrefixFactor creates the default conversion function between two prefixes.
+// It returns a conversation function for the value.
 func GetPrefixPrefixFactor(in Prefix, out Prefix) func(value interface{}) interface{} {
 	var factor = 1.0
 	var in_prefix = float64(in)
@@ -144,14 +147,17 @@ func convertTempF2TempC(value interface{}) interface{} {
 	return value
 }
 
-// If we only have strings with the prefixes, this is a handy wrapper
+// GetPrefixStringPrefixStringFactor is a wrapper for GetPrefixPrefixFactor with string inputs instead
+// of prefixes. It also returns a conversation function for the value.
 func GetPrefixStringPrefixStringFactor(in string, out string) func(value interface{}) interface{} {
 	var i Prefix = NewPrefix(in)
 	var o Prefix = NewPrefix(out)
 	return GetPrefixPrefixFactor(i, o)
 }
 
-// Get the conversion function and resulting unit for a unit and a prefix
+// GetUnitPrefixFactor gets the conversion function and resulting unit for a unit and a prefix. This is
+// the most common case where you have some input unit and want to convert it to the same unit but with
+// a different prefix. The returned unit represents the value after conversation.
 func GetUnitPrefixFactor(in Unit, out Prefix) (func(value interface{}) interface{}, Unit) {
 	outUnit := NewUnit(in.Short())
 	if outUnit.Valid() {
@@ -162,19 +168,23 @@ func GetUnitPrefixFactor(in Unit, out Prefix) (func(value interface{}) interface
 	return nil, INVALID_UNIT
 }
 
-// Get the conversion function and resulting unit for a unit and a prefix as string
+// GetUnitPrefixStringFactor gets the conversion function and resulting unit for a unit and a prefix as string.
+// It is a wrapper for GetUnitPrefixFactor
 func GetUnitPrefixStringFactor(in Unit, out string) (func(value interface{}) interface{}, Unit) {
 	var o Prefix = NewPrefix(out)
 	return GetUnitPrefixFactor(in, o)
 }
 
-// Get the conversion function and resulting unit for a unit and a prefix when both are only string representations
+// GetUnitStringPrefixStringFactor gets the conversion function and resulting unit for a unit and a prefix when both are only string representations.
+// This is just a wrapper for GetUnitPrefixFactor with the given input unit and the desired output prefix.
 func GetUnitStringPrefixStringFactor(in string, out string) (func(value interface{}) interface{}, Unit) {
 	var i = NewUnit(in)
 	return GetUnitPrefixStringFactor(i, out)
 }
 
-// Get the conversion function and (maybe) error for unit to unit conversion
+// GetUnitUnitFactor gets the conversion function and (maybe) error for unit to unit conversion.
+// It is basically a wrapper for GetPrefixPrefixFactor with some special cases for temperature
+// conversion between Fahrenheit and Celsius.
 func GetUnitUnitFactor(in Unit, out Unit) (func(value interface{}) interface{}, error) {
 	if in.getMeasure() == TemperatureC && out.getMeasure() == TemperatureF {
 		return convertTempC2TempF, nil
@@ -186,7 +196,8 @@ func GetUnitUnitFactor(in Unit, out Unit) (func(value interface{}) interface{},
 	return GetPrefixPrefixFactor(in.getPrefix(), out.getPrefix()), nil
 }
 
-// Create a new unit out of a string representing a unit like 'Mbyte/s' or 'GHz'.
+// NewUnit creates a new unit out of a string representing a unit like 'Mbyte/s' or 'GHz'.
+// It uses regular expressions to detect the prefix, unit and (maybe) unit denominator.
 func NewUnit(unitStr string) Unit {
 	u := &unit{
 		prefix:     InvalidPrefix,