From c17cc4a7e61d77c47d57258f0cc3ffa9ed75b47e Mon Sep 17 00:00:00 2001
From: Dave Shanley <dave@quobix.com>
Date: Fri, 16 Sep 2022 14:03:05 -0400
Subject: [PATCH] Adding more docs to high level models.

Cleaning things that are not used.
---
 datamodel/constants.go               |  9 +++++++--
 datamodel/high/v3/document.go        |  1 +
 datamodel/high/v3/encoding.go        |  2 +-
 datamodel/high/v3/header.go          |  5 +++++
 datamodel/high/v3/label_constants.go | 10 ----------
 datamodel/high/v3/link.go            |  4 ++++
 datamodel/high/v3/media_type.go      |  2 ++
 7 files changed, 20 insertions(+), 13 deletions(-)
 delete mode 100644 datamodel/high/v3/label_constants.go

diff --git a/datamodel/constants.go b/datamodel/constants.go
index 93f5e25..961fff3 100644
--- a/datamodel/constants.go
+++ b/datamodel/constants.go
@@ -21,8 +21,13 @@ import (
 
 // Constants used by utilities to determine the version of OpenAPI that we're referring to.
 const (
-	OAS2  = "oas2"
-	OAS3  = "oas3"
+	// OAS2 represents Swagger Documents
+	OAS2 = "oas2"
+
+	// OAS3 represents OpenAPI 3.0+ Documents
+	OAS3 = "oas3"
+
+	// OAS31 represents OpenAPI 3.1+ Documents
 	OAS31 = "oas3_1"
 )
 
diff --git a/datamodel/high/v3/document.go b/datamodel/high/v3/document.go
index b2de451..d46fcb0 100644
--- a/datamodel/high/v3/document.go
+++ b/datamodel/high/v3/document.go
@@ -116,6 +116,7 @@ func NewDocument(document *low.Document) *Document {
 	return d
 }
 
+// GoLow returns the low-level Document that was used to create the high level one.
 func (d *Document) GoLow() *low.Document {
 	return d.low
 }
diff --git a/datamodel/high/v3/encoding.go b/datamodel/high/v3/encoding.go
index aa6e54f..6d8b92b 100644
--- a/datamodel/high/v3/encoding.go
+++ b/datamodel/high/v3/encoding.go
@@ -9,7 +9,7 @@ import (
 )
 
 // Encoding represents an OpenAPI 3+ Encoding object
-// - https://spec.openapis.org/oas/v3.1.0#encoding-object
+//  - https://spec.openapis.org/oas/v3.1.0#encoding-object
 type Encoding struct {
 	ContentType   string
 	Headers       map[string]*Header
diff --git a/datamodel/high/v3/header.go b/datamodel/high/v3/header.go
index dd37fe9..7afee6c 100644
--- a/datamodel/high/v3/header.go
+++ b/datamodel/high/v3/header.go
@@ -10,6 +10,8 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// Header represents a high-level OpenAPI 3+ Header object that is backed by a low-level one.
+//  - https://spec.openapis.org/oas/v3.1.0#header-object
 type Header struct {
 	Description     string
 	Required        bool
@@ -26,6 +28,7 @@ type Header struct {
 	low             *low.Header
 }
 
+// NewHeader creates a new high-level Header instance from a low-level one.
 func NewHeader(header *low.Header) *Header {
 	h := new(Header)
 	h.low = header
@@ -49,10 +52,12 @@ func NewHeader(header *low.Header) *Header {
 	return h
 }
 
+// GoLow returns the low-level Header instance used to create the high-level one.
 func (h *Header) GoLow() *low.Header {
 	return h.low
 }
 
+// ExtractHeaders will extract a hard to navigate low-level Header map, into simple high-level one.
 func ExtractHeaders(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.Header]) map[string]*Header {
 	extracted := make(map[string]*Header)
 	for k, v := range elements {
diff --git a/datamodel/high/v3/label_constants.go b/datamodel/high/v3/label_constants.go
deleted file mode 100644
index fbbcc3d..0000000
--- a/datamodel/high/v3/label_constants.go
+++ /dev/null
@@ -1,10 +0,0 @@
-// Copyright 2022 Princess B33f Heavy Industries / Dave Shanley
-// SPDX-License-Identifier: MIT
-
-package v3
-
-const (
-	NameLabel         = "name"
-	DescriptionLabel  = "description"
-	ExternalDocsLabel = "externalDocs"
-)
diff --git a/datamodel/high/v3/link.go b/datamodel/high/v3/link.go
index 6132ecf..31bf4ea 100644
--- a/datamodel/high/v3/link.go
+++ b/datamodel/high/v3/link.go
@@ -8,6 +8,8 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// Link represents an OpenAPI 3+ Link object that is backed by a low-level one.
+//  - https://spec.openapis.org/oas/v3.1.0#link-object
 type Link struct {
 	OperationRef string
 	OperationId  string
@@ -19,6 +21,7 @@ type Link struct {
 	low          *low.Link
 }
 
+// NewLink will create a new high-level Link instance from a low-level one.
 func NewLink(link *low.Link) *Link {
 	l := new(Link)
 	l.low = link
@@ -38,6 +41,7 @@ func NewLink(link *low.Link) *Link {
 	return l
 }
 
+// GoLow will return the low-level Link instance used to create the high-level one.
 func (l *Link) GoLow() *low.Link {
 	return l.low
 }
diff --git a/datamodel/high/v3/media_type.go b/datamodel/high/v3/media_type.go
index 794cb12..68f9909 100644
--- a/datamodel/high/v3/media_type.go
+++ b/datamodel/high/v3/media_type.go
@@ -11,6 +11,8 @@ import (
 	"sync"
 )
 
+// MediaType represents a high-level OpenAPI MediaType object that is backed by a low-level one.
+//  - https://spec.openapis.org/oas/v3.1.0#media-type-object
 type MediaType struct {
 	Schema     *base.SchemaProxy
 	Example    any