Add/Update/Correct GoDoc comments on /lib symbols (#6099)

* Add/Update/Correct GoDoc comments on cache-control-related symbols

* Formatting for caching symbol GoDoc comments

* Add/Update/Correct GoDoc comments for email-related structures

* Add/Update/Correct GoDoc comments on URL-related structures

* Add/Update/Correct GoDoc comments for logging-related structures

* Add package GoDoc documentation for lib/go-log/

* Add/Update/Correct GoDoc comments on "backoff"-related structures

* Add/Update/Correct GoDoc comment on encryption-related utilities

* Add/Update/Correct GoDoc comments on sting/error-joining-related utilities

* Add/Update/Correct GoDoc comments on IP address-related utilities

* Add/Update/Correct GoDoc comments on variable-typed numerics utilities

* Add/Update/Correct GoDoc comments on string slice utilities

* Add package GoDoc documentation for lib/go-util

* Add package GoDoc documentation for lib/go-atscfg

* Add/Update/Correct GoDoc comments for astats.config symbols

* Add/Update/Correct GoDoc comments for generic/widely used ATS configuration file-related structures

* Add/Update/Correct GoDoc comments for 50-ats.rules symbols

* Add/Update/Correct GoDoc comments for bg_fetch.config symbols

* Add/Update/Correct GoDoc comments for cache.config symbols

* Add/Update/Correct GoDoc comments for chkconfig symbols

* Add/Update/Correct GoDoc comments on drop_qstring.config symbols

* Add/Update/Correct GoDoc comments on 12M_facts symbols

* Add/Update/Correct GoDoc comments on hdr_rw_*.config symbols

* Add/Update/Correct GoDoc comments on hosting.config symbols

* Add/Update/Correct GoDoc comments on ip_allow.config symbols

* Add/Update/Correct GoDoc comments on ip_allow.yaml-related symbols

* Add/Update/Correct GoDoc comments on logging.config symbols

* Add/Update/Correct GoDoc comments on logging.yaml symbols

* Add/Update/Correct GoDoc comments for logs_xml.config symbols

* Add/Update/Correct GoDoc comments for configuration file "meta" symbols

* Add/Update/Correct GoDoc comments for package-related symbols

* Add/Update/Correct GoDoc comments for parent.config symbols

* Add/Update/Correct GoDoc comments for records.config symbols

* Add/Update/Correct GoDoc comments for regex_remap.config symbols

* Add/Update/Correct GoDoc comments for regex_revalidate.config symbols

* Add/Update/Correct GoDoc comments for remap.config symbols

* Add/Update/Correct GoDoc comments for "server" cache.config symbols

* Add/Update/Correct GoDoc comments for arbitrary file generation symbols

* Add/Update/Correct GoDoc comments for set_dscp.config symbols

* Add/Update/Correct GoDoc comments for sni.yaml symbols

* Add/Update/Correct GoDoc comments on ssl_multicert.config symbols

* Add/Update/Correct GoDoc comments on ssl_server_name.yaml symbols.

* Add/Update/Correct GoDoc comments for storage.config symbols

* Add/Update/Correct GoDoc comments for sysctl.conf symbols

* Add/Update/Correct GoDoc comments for uri_signing.config symbols

* Add/Update/Correct GoDoc comments for url_sig.config symbols

* Add/Update/Correct GoDoc comments for volume.config symbols

* Fix spelling errors

* Remove incorrect warning

* Update chkconfig GoDoc comments based on questions answered in the review

* Remove comments about removing constants that are only used tautologically

* Add/Update/Correct GoDoc comments for abstract parentage utilities

* Add/Update/Correct GoDoc comments for strategies.yaml symbols

* Add/Update/Correct GoDoc comments for symbols related to Delivery Service SSL/URI/URL keys

* Add/Update/Correct GoDoc comments for symbols related to servers

* Add/Update/Correct GoDoc comments for symbols related to Traffic Router

* Add/Update/Delete GoDoc comments for symbols related to emulated enumerated types

* Add/Update/Correct GoDoc comments for symbols related to content invalidation jobs

* Add/Update/Correct GoDoc comments for symbols related to users

* Go fmt

lib/go-atscfg/astatsdotconfig.go

@@ -23,10 +23,20 @@ import (
 	"github.com/apache/trafficcontrol/v8/lib/go-tc"
 )
 
+// AstatsSeparator is the string used by astats.config to separate
+// configuration option names from values.
 const AstatsSeparator = "="
+
+// AstatsFileName is the name of the file used to contain configuration for the
+// astats_over_http Traffic Server plugin.
 const AstatsFileName = "astats.config"
 
+// ContentTypeAstatsDotConfig is the MIME type of the content of astats.config
+// file.
 const ContentTypeAstatsDotConfig = ContentTypeTextASCII
+
+// LineCommentAstatsDotConfig is the string used to mark the beginning of a
+// line comment as understood by parsers of astats.config files.
 const LineCommentAstatsDotConfig = LineCommentHash
 
 // AStatsDotConfigOpts contains settings to configure generation options.
@@ -37,6 +47,11 @@ type AStatsDotConfigOpts struct {
 	HdrComment string
 }
 
+// MakeAStatsDotConfig constructs an astats.config file for the given server
+// with the given Parameters and header comment content.
+//
+// TODO: Rename to 'MakeAstatsDotConfig' for consistency with other exported
+// symbols?
 func MakeAStatsDotConfig(
 	server *Server,
 	serverParams []tc.ParameterV5,

lib/go-atscfg/atscfg.go

@@ -32,23 +32,103 @@ import (
 	"github.com/apache/trafficcontrol/v8/lib/go-tc"
 )
 
+// InvalidID is used as a placeholder value when determining the ID of a parent
+// Cache Group.
+//
+// This is not strictly invalid; when a Cache Group's Parent's ID is "detected"
+// as this value, then it may simply mean that the Cache Group is "top-level",
+// and has no parent.
+//
+// TODO: unexport this? It's highly specific to this package, and isn't used
+// anywhere else.
 const InvalidID = -1
-const DefaultATSVersion = "5" // TODO Emulates Perl; change to 6? ATC no longer officially supports ATS 5.
-// todo also unused
+
+// DefaultATSVersion is the version of Traffic Server assumed when one is not
+// directly specified in a server's Parameters.
+//
+// TODO: Emulates Perl; change to 6? ATC no longer officially supports ATS 5.
+const DefaultATSVersion = "5"
+
+// HeaderCommentDateFormat is an unused format for dates and times.
+//
+// TODO: Remove this, it's unused.
 const HeaderCommentDateFormat = "Mon Jan 2 15:04:05 MST 2006"
+
+// ContentTypeTextASCII is the MIME type for plain text using an ASCII
+// character set.
+//
+// TODO: Move to lib/go-rfc package?
 const ContentTypeTextASCII = `text/plain; charset=us-ascii`
 
+// LineCommentHash is the string that denotes the beginning of a line comment,
+// for grammars that use the number sign for line comments.
+//
+// TODO: Unexport? This is only used, it seems, to group multiple usages into a
+// single symbol not used outside this package. It's conceivable to want to
+// know the line comment string for a given grammar, but it's unlikely that
+// anyone importing this package would find an alias for "#" itself helpful,
+// with no other attached semantics.
 const LineCommentHash = "#"
+
+// ConfigSuffix is a suffix (or "file extension") appended to many
+// configuration file names, most notably those for the Header Rewrite Traffic
+// Server plugin.
+//
+// TODO: Unexport? This is only used by the header rewrite configuration file
+// generation functions, and doesn't have much practical purpose outside of
+// that limited usage.
 const ConfigSuffix = ".config"
+
+// TsDefaultRequestHeaderMaxSize is the default maximum request header size
+// that will be allowed by ATS unless otherwise specified on a server's
+// Profile.
+//
+// For more information, refer to the ATS documentation for the reconds.config
+// configuration option 'proxy.config.http.request_header_max_size'.
 const TsDefaultRequestHeaderMaxSize = 131072
 
+// DeliveryServiceID is used internally to represent a Delivery Service ID.
+//
+// TODO: Unexport? This isn't used outside of this package. Alternatively:
+// remove? lib/go-tc and cache-config/* use ints, so all this is doing is
+// causing spurious casting back and forth.
 type DeliveryServiceID int
+
+// ProfileID is used internally to represent a Profile ID.
+//
+// TODO: Unexport? This isn't used outside of this package. Alternatively:
+// remove? lib/go-tc and cache-config/* use ints, so all this is doing is
+// causing spurious casting back and forth.
 type ProfileID int
+
+// ServerID is used internally to represent a server ID.
+//
+// TODO: Unexport? This isn't used outside of this package. Alternatively:
+// remove? lib/go-tc and cache-config/* use ints, so all this is doing is
+// causing spurious casting back and forth.
 type ServerID int
 
+// ProfileName is used internally to represent a Profile Name.
 type ProfileName string
+
+// TopologyName is used internally to represent a Topology Name.
+//
+// Deprecated: github.com/apache/trafficcontrol/lib/go-tc provides the
+// an identical type by the same name, but that is the type actually used
+// by the Go client and Traffic Ops. Therefore, new code should use that
+// type instead of this one.
 type TopologyName string
+
+// CacheGroupType is used internally to represent the Name of the Type of a
+// Cache Group.
+//
+// TODO: Unexport? This isn't used outside of this package. Alternatively:
+// remove? lib/go-tc and cache-config/* use strings, so all this is doing is
+// causing spurious casting back and forth.
 type CacheGroupType string
+
+// ServerCapability is used to represent the Name of a Capability that a server
+// has OR that a Delivery Service requires.
 type ServerCapability string
 
 // Server is a tc.Server for the latest lib/go-tc and traffic_ops/vx-client type.
@@ -66,9 +146,10 @@ type DeliveryService tc.DeliveryServiceV5
 // but to only have to change it here, and the places where breaking symbol changes were made.
 type InvalidationJob tc.InvalidationJobV4
 
-// ServerUdpateStatus is a tc.ServerUdpateStatus for the latest lib/go-tc and traffic_ops/vx-client type.
-// This allows atscfg to not have to change the type everywhere it's used, every time ATC changes the base type,
-// but to only have to change it here, and the places where breaking symbol changes were made.
+// ServerUpdateStatus is a tc.ServerUpdateStatus for the latest lib/go-tc and
+// traffic_ops/vx-client type. This allows atscfg to not have to change the type
+// everywhere it's used, every time ATC changes the base type, but to only have
+// to change it here, and the places where breaking symbol changes were made.
 type ServerUpdateStatus tc.ServerUpdateStatusV5
 
 //type CDN tc.CDNV5
@@ -351,7 +432,6 @@ func trimParamUnderscoreNumSuffix(paramName string) string {
 }
 
 // topologyIncludesServer returns whether the given topology includes the given server.
-// todo also unused
 func topologyIncludesServer(topology tc.Topology, server *tc.Server) bool {
 	for _, node := range topology.Nodes {
 		if node.Cachegroup == server.Cachegroup {
@@ -379,6 +459,7 @@ func topologyIncludesServerNullable(topology tc.TopologyV5, server *Server) (boo
 // Caches immediately before the origin are the TopologyCacheTierLast, even for MSO.
 type TopologyCacheTier string
 
+// These are the allowed values for a TopologyCacheTier.
 const (
 	TopologyCacheTierFirst   = TopologyCacheTier("first")
 	TopologyCacheTierInner   = TopologyCacheTier("inner")
@@ -793,6 +874,12 @@ type DeliveryServiceServer struct {
 	DeliveryService int `json:"d"`
 }
 
+// JobsToInvalidationJobs converts a set of tc.Job structures into their
+// equivalent InvalidationJob structures, by calling JobToInvalidationJob on
+// each of them in turn.
+//
+// This will bail on the first error encountered when converting, so other jobs
+// afterward may also have problems, but they won't be reported.
 func JobsToInvalidationJobs(oldJobs []tc.Job) ([]InvalidationJob, error) {
 	jobs := make([]InvalidationJob, len(oldJobs), len(oldJobs))
 	err := error(nil)
@@ -805,14 +892,37 @@ func JobsToInvalidationJobs(oldJobs []tc.Job) ([]InvalidationJob, error) {
 	return jobs, nil
 }
 
-const JobV4TimeFormat = time.RFC3339Nano
-const JobLegacyTimeFormat = "2006-01-02 15:04:05-07"
-const JobLegacyRefetchSuffix = `##REFETCH##`
-const JobLegacyRefreshSuffix = `##REFRESH##`
-const JobLegacyParamPrefix = "TTL:"
-const JobLegacyParamSuffix = "h"
-const JobLegacyKeyword = "PURGE"
+// These are the formats for the "lastUpdated" timestamps of Content
+// Invalidation Jobs in different Traffic Ops API versions.
+const (
+	// The format in API versions 4.0 and later.
+	JobV4TimeFormat = time.RFC3339Nano
+	// The format in API versions prior to 4.0.
+	JobLegacyTimeFormat = "2006-01-02 15:04:05-07"
+)
+
+// These special suffixes when found on a rule override the default type of a
+// Content Invalidation Job.
+// Deprecated: these are no longer necessary in Traffic Ops API versions 4.0 and
+// later.
+const (
+	JobLegacyRefetchSuffix = `##REFETCH##`
+	JobLegacyRefreshSuffix = `##REFRESH##`
+)
+
+// These strings are used to parse legacy representations of Content
+// Invalidation Jobs.
+// Deprecated: When the Traffic Ops API version 4.0 representation of Content
+// Invalidation Jobs becomes standard (i.e. when 3.x API version support is
+// dropped) these will have no meaning or purpose.
+const (
+	JobLegacyParamPrefix = "TTL:"
+	JobLegacyParamSuffix = "h"
+	JobLegacyKeyword     = "PURGE"
+)
 
+// JobToInvalidationJob converts a tc.Job to an InvalidationJob. If the
+// conversion fails, an error is returned.
 func JobToInvalidationJob(jb tc.Job) (InvalidationJob, error) {
 	startTime := tc.Time{}
 	if err := json.Unmarshal([]byte(`"`+jb.StartTime+`"`), &startTime); err != nil {
@@ -838,7 +948,7 @@ func JobToInvalidationJob(jb tc.Job) (InvalidationJob, error) {
 	}, nil
 }
 
-// FilterServers returns the servers for which filter returns true
+// FilterServers returns the servers for which filter returns true.
 func FilterServers(servers []Server, filter func(sv *Server) bool) []Server {
 	// TODO add warning/error feature?
 	filteredServers := []Server{}

lib/go-atscfg/atsdotrules.go

@@ -25,8 +25,22 @@ import (
 	"github.com/apache/trafficcontrol/v8/lib/go-tc"
 )
 
+// ATSDotRulesFileName is the name of a "rules" configuration file.
+//
+// TODO: This isn't actually correct. This is just the ConfigFile value that a
+// cache server's Profile's Drive_Prefix, Drive_Letters, RAM_Drive_Prefix, and
+// RAM_Drive_Letters Parameters must have for generation to be successful (in
+// fact it seems to panic if those aren't found), but the actual name of the
+// file for which MakeATSDotRules outputs content is '50-ats.rules'. Is this
+// misleading? Maybe it just doesn't even need to be exported? Or exist at all?
 const ATSDotRulesFileName = StorageFileName
+
+// ContentTypeATSDotRules is the MIME type of the contents of a 50-ats.rules
+// file.
 const ContentTypeATSDotRules = ContentTypeTextASCII
+
+// LineCommentATSDotRules is the string used by parsers of 50-ats.rules to
+// determine that the rest of the current line's content is a comment.
 const LineCommentATSDotRules = LineCommentHash
 
 // ATSDotRulesOpts contains settings to configure generation options.
@@ -37,6 +51,8 @@ type ATSDotRulesOpts struct {
 	HdrComment string
 }
 
+// MakeATSDotRules constructs a '50-ats.rules' file for the given server with
+// the given parameters and header comment content.
 func MakeATSDotRules(
 	server *Server,
 	serverParams []tc.ParameterV5,

lib/go-atscfg/bgfetchdotconfig.go

@@ -19,7 +19,12 @@ package atscfg
  * under the License.
  */
 
+// ContentTypeBGFetchDotConfig is the MIME type of the contents of a
+// bg_fetch.config file.
 const ContentTypeBGFetchDotConfig = ContentTypeTextASCII
+
+// LineCommentBGFetchDotConfig is the string understood by parsers of
+// bg_fetch.config files to be the beginning of a line comment.
 const LineCommentBGFetchDotConfig = LineCommentHash
 
 // BGFetchDotConfigOpts contains settings to configure generation options.
@@ -30,6 +35,8 @@ type BGFetchDotConfigOpts struct {
 	HdrComment string
 }
 
+// MakeBGFetchDotConfig constructs a 'bg_fetch.config' file for the given
+// server with the given header comment content.
 func MakeBGFetchDotConfig(
 	server *Server,
 	opt *BGFetchDotConfigOpts,

lib/go-atscfg/cachedotconfig.go

@@ -27,7 +27,12 @@ import (
 	"github.com/apache/trafficcontrol/v8/lib/go-tc"
 )
 
+// ContentTypeCacheDotConfig is the MIME type of the contents of a cache.config
+// file.
 const ContentTypeCacheDotConfig = ContentTypeTextASCII
+
+// LineCommentCacheDotConfig is the string that signifies the beginning of a
+// line comment in the grammar of a cache.config file.
 const LineCommentCacheDotConfig = LineCommentHash
 
 // CacheDotConfigOpts contains settings to configure generation options.

lib/go-atscfg/chkconfig.go

@@ -26,17 +26,37 @@ import (
 	"github.com/apache/trafficcontrol/v8/lib/go-tc"
 )
 
+// ChkconfigFileName is the name of the ckconfig configuration file.
 const ChkconfigFileName = `chkconfig`
+
+// ChkconfigParamConfigFile is the ConfigFile value of Parameters that affect
+// the generation of the chkconfig configuration file.
 const ChkconfigParamConfigFile = `chkconfig`
+
+// ContentTypeChkconfig is the MIME content type of the contents of the
+// chkconfig configuration file.
+//
+// Note that the GoDoc for MakeChkconfig says "This is a JSON object, and should
+// be served with an 'application/json' Content-Type." but actually the file
+// contents on disk are not JSON-encoded.
 const ContentTypeChkconfig = ContentTypeTextASCII
+
+// LineCommentChkconfig is the string that signifies the start of a line comment
+// in the grammar of a chkconfig configuration file.
 const LineCommentChkconfig = LineCommentHash
 
 // ChkconfigOpts contains settings to configure generation options.
 type ChkconfigOpts struct {
 }
 
 // MakeChkconfig returns the 'chkconfig' ATS config file endpoint.
-// This is a JSON object, and should be served with an 'application/json' Content-Type.
+//
+// This is a JSON object, and should be served with an 'application/json'
+// Content-Type.
+//
+// TODO: rename/rework? We systemd now, after all. Also, this may be unused as
+// t3c now generates the contents of the file specially without calling into
+// this function, possibly.
 func MakeChkconfig(
 	serverParams []tc.ParameterV5,
 	opt *ChkconfigOpts,

lib/go-atscfg/doc.go

@@ -0,0 +1,22 @@
+// Package atscfg contains logic for generating Apache Traffic Server
+// configuration files from ATC objects and concepts.
+package atscfg
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */

lib/go-atscfg/dropqstringdotconfig.go

@@ -23,9 +23,22 @@ import (
 	"github.com/apache/trafficcontrol/v8/lib/go-tc"
 )
 
+// DropQStringDotConfigFileName is the name of the drop_qstring.config file -
+// this is also the ConfigFile value of Parameters that are able to affect the
+// contents of this file.
 const DropQStringDotConfigFileName = "drop_qstring.config"
+
+// DropQStringDotConfigParamName is the Name a Parameter must have to dictate
+// the contents of drop_qstring.config - Parameters by other Names (even in the
+// correct ConfigFile) are ignored.
 const DropQStringDotConfigParamName = "content"
+
+// ContentTypeDropQStringDotConfig is the MIME type of the contents of a
+// drop_qstring.config file.
 const ContentTypeDropQStringDotConfig = ContentTypeTextASCII
+
+// LineCommentDropQStringDotConfig is the string that signifies the start of a
+// line comment in the grammar of a drop_qstring.config file.
 const LineCommentDropQStringDotConfig = LineCommentHash
 
 // DropQStringDotConfigOpts contains settings to configure generation options.
@@ -36,6 +49,8 @@ type DropQStringDotConfigOpts struct {
 	HdrComment string
 }
 
+// MakeDropQStringDotConfig constructs a drop_qstring.config file for the given
+// server with the given Parameters and header comment content.
 func MakeDropQStringDotConfig(
 	server *Server,
 	serverParams []tc.ParameterV5,