Housekeeping - Doc sweep and dead code removal (#70)

## Improvements:

* Added documentation to the `definitions` package

* Removed some dead structs and code

* Fixed an inconsistency in `CHANGELOG.md`

----------------------------------------

## Important note:

This is technically a minor breaking change as several public items were removed.
That said, these structures are entirely unused and should not be implicated in any consumer code.

A list of removals:

* `EnumValidator`  (`struct`)
* `EnumValidators` (`field` in `Models` struct)
* `OrderedIdent` (`struct`)
* `EnsureValidHttpVerb` (`function`)


A major version release would be far more disruptive here.

Author: yuval-po

changelog/CHANGELOG.md

@@ -1,10 +1,10 @@
 # Gleece Changelog
 
-## Gleece v2.1.0
+## Gleece v2.0.0
 
 ### Summary
 
-*Gleece* 2.1 brings in concrete support for type aliases, map input/outputs and an overhauled type resolution system.
+*Gleece* 2.0 brings in concrete support for type aliases, map input/outputs and an overhauled type resolution system.
 
 ### Features
 

definitions/consts.go

@@ -1,8 +1,12 @@
 package definitions
 
+// The name of the RFC7807 error struct
 const Rfc7807ErrorName = "Rfc7807Error"
+
+// The full package path of the RFC7807 error struct
 const Rfc7807ErrorFullPackage = "github.com/gopher-fleece/runtime"
 
+// Defines Gleece's supported routing engines
 var SupportedRoutingEngineStrings = []string{
 	string(RoutingEngineGin),
 	string(RoutingEngineEcho),

definitions/enums.go

@@ -11,6 +11,7 @@ const (
 	PassedInForm   ParamPassedIn = "Form"
 )
 
+// An HTTP verb such as POST or GET
 type HttpVerb string
 
 const (
@@ -25,6 +26,7 @@ const (
 	HttpConnect HttpVerb = "CONNECT"
 )
 
+// An HTTP Content-Type
 type ContentType string
 
 const (
@@ -44,11 +46,17 @@ const (
 	ContentTypeCSS            ContentType = "text/css"
 )
 
+// An API method's visibility in the generated OpenAPI schema
 type HideMethodType string
 
 const (
-	HideMethodNever     HideMethodType = "Never"
-	HideMethodAlways    HideMethodType = "Always"
+	// Never hide this endpoint
+	HideMethodNever HideMethodType = "Never"
+	// Always hide this endpoint
+	HideMethodAlways HideMethodType = "Always"
+	// ***NOT YET IMPLEMENTED***
+	//
+	// Hide this method if the given condition is met
 	HideMethodCondition HideMethodType = "Condition"
 )
 
@@ -79,6 +87,8 @@ const (
 	HttpAuthSchemeVapid HttpAuthScheme = "vapid"
 )
 
+// The security schema type for API authorization,
+// that is, the definition of authentication the API server
 type SecuritySchemeType string
 
 const (
@@ -88,6 +98,7 @@ const (
 	HTTP          SecuritySchemeType = "http"
 )
 
+// The way in which consumers are to pass authorization to the API server
 type SecuritySchemeIn string
 
 const (
@@ -97,6 +108,7 @@ const (
 	InCookie SecuritySchemeIn = "cookie"
 )
 
+// The API server's underlying routing engine
 type RoutingEngineType string
 
 const (

definitions/helpers.go

@@ -97,6 +97,7 @@ var validHttpStatusCode = map[uint]struct{}{
 	uint(runtime.StatusNetworkAuthenticationRequired): {},
 }
 
+// GetValidHttpVerbs returns a list of all valid HTTP verbs
 func GetValidHttpVerbs() []string {
 	verbs := make([]string, 0, len(validHttpVerbs))
 	for verb := range validHttpVerbs {
@@ -105,12 +106,14 @@ func GetValidHttpVerbs() []string {
 	return verbs
 }
 
+// GetRouteSupportedHttpVerbs returns a list of all HTTP verbs that are valid in the context of an API Endpoint
 func GetRouteSupportedHttpVerbs() []string {
 	verbs := common.MapKeys(routeSupportedHttpVerbs)
 	slices.Sort(verbs)
 	return verbs
 }
 
+// GetValidHttpStatusCodes returns a list of all known/valid HTTP Status Codes
 func GetValidHttpStatusCodes() []uint {
 	codes := make([]uint, 0, len(validHttpStatusCode))
 	for code := range validHttpStatusCode {
@@ -119,28 +122,27 @@ func GetValidHttpStatusCodes() []uint {
 	return codes
 }
 
+// IsValidHttpVerb determines whether a given string is a valid HTTP verb
 func IsValidHttpVerb(verb string) bool {
 	_, exists := validHttpVerbs[verb]
 	return exists
 }
 
+// IsValidRouteHttpVerb determines whether a given string is an HTTP verb
+// that is valid in the context of an API endpoint
 func IsValidRouteHttpVerb(verb string) bool {
 	_, exists := routeSupportedHttpVerbs[verb]
 	return exists
 }
 
-func EnsureValidHttpVerb(verb string) HttpVerb {
-	if IsValidHttpVerb(verb) {
-		return HttpVerb(verb)
-	}
-	panic(fmt.Sprintf("'%s' is not a valid HTTP verb", verb))
-}
-
+// IsValidHttpStatusCode determines whether the given code is a known, valid HTTP Status Code
 func IsValidHttpStatusCode(code uint) bool {
 	_, exists := validHttpStatusCode[code]
 	return exists
 }
 
+// ConvertToHttpStatus attempts to convert the given code into an HTTP Status Code.
+// Returns an error if the given code is invalid.
 func ConvertToHttpStatus(code string) (runtime.HttpStatusCode, error) {
 	parsed, err := strconv.ParseUint(code, 10, 32)
 	if err != nil {
@@ -154,6 +156,9 @@ func ConvertToHttpStatus(code string) (runtime.HttpStatusCode, error) {
 	return runtime.HttpStatusCode(parsedCode), nil
 }
 
+// PermissionStringToFileMod converts the given permission string into a FileMode.
+//
+// Input is expected to be a valid octal permission value like '0777'
 func PermissionStringToFileMod(permissionString string) (os.FileMode, error) {
 	permission, err := strconv.ParseUint(permissionString, 8, 32)
 	// A proper mask needs to account for sticky/setuid/setgid bitflags