Misc doc, code refactoring to improve documentation

3 files changed, 29 insertions, 0 deletions

diff --git a/markup/converter/hooks/hooks.go b/markup/converter/hooks/hooks.go
index a59da939e..7eede0710 100644
--- a/markup/converter/hooks/hooks.go
+++ b/markup/converter/hooks/hooks.go
@@ -26,30 +26,56 @@ import (
 var _ AttributesOptionsSliceProvider = (*attributes.AttributesHolder)(nil)
 
 type AttributesProvider interface {
+	// Attributes passed in from Markdown (e.g. { attrName1=attrValue1 attrName2="attr Value 2" }).
 	Attributes() map[string]any
 }
 
 type LinkContext interface {
+	// The Page being rendered.
 	Page() any
+
+	// The link URL.
 	Destination() string
+
+	// The link title attribute.
 	Title() string
+
+	// The rendered (HTML) text.
 	Text() hstring.RenderedString
+
+	// The plain variant of Text.
 	PlainText() string
 }
 
 type ImageLinkContext interface {
 	LinkContext
+
+	// Returns true if this is a standalone image and the config option
+	// markup.goldmark.parser.wrapStandAloneImageWithinParagraph is disabled.
 	IsBlock() bool
+
+	// Zero-based ordinal for all the images in the current document.
 	Ordinal() int
 }
 
+// CodeblockContext is the context passed to a code block render hook.
 type CodeblockContext interface {
 	AttributesProvider
 	text.Positioner
+
+	// Chroma highlighting processing options. This will only be filled if Type is a known Chroma Lexer.
 	Options() map[string]any
+
+	// The type of code block. This will be the programming language, e.g. bash, when doing code highlighting.
 	Type() string
+
+	// The text between the code fences.
 	Inner() string
+
+	// Zero-based ordinal for all code blocks in the current document.
 	Ordinal() int
+
+	// The owning Page.
 	Page() any
 }
 
diff --git a/markup/highlight/highlight.go b/markup/highlight/highlight.go
index 010c941f7..b74997700 100644
--- a/markup/highlight/highlight.go
+++ b/markup/highlight/highlight.go
@@ -157,10 +157,12 @@ type HightlightResult struct {
 	highlighted template.HTML
 }
 
+// Wrapped returns the highlighted code wrapped in a <div>, <pre> and <code> tag.
 func (h HightlightResult) Wrapped() template.HTML {
 	return h.highlighted
 }
 
+// Inner returns the highlighted code without the wrapping <div>, <pre> and <code> tag, suitable for inline use.
 func (h HightlightResult) Inner() template.HTML {
 	return h.highlighted[h.innerLow:h.innerHigh]
 }
diff --git a/markup/markup.go b/markup/markup.go
index 1345867f9..aefa50867 100644
--- a/markup/markup.go
+++ b/markup/markup.go
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package markup contains the markup handling (e.g. Markdown).
 package markup
 
 import (