refactor: clean up verbose and redundant comments

Trim or remove comments that:
- State the obvious (function names already convey purpose)
- Repeat what the code clearly shows
- Are excessively long without adding value

Keep comments that explain *why*, not *what*.

internal/contracts/main_result.go

@@ -22,14 +22,10 @@ import (
 )
 
 // MainResult represents one element of the `results` array.
-//
-// The API returns many additional keys beyond what templates use. To keep the
-// contract stable for proxying/merging, we preserve all unknown keys in
-// `raw` and re-emit them via MarshalJSON.
+// Unknown keys are preserved in `raw` and re-emitted via MarshalJSON.
 type MainResult struct {
 	raw map[string]any
 
-	// Common fields used by templates (RSS uses: title, url, content, pubdate).
 	Template  string `json:"template"`
 	Title     string `json:"title"`
 	Content   string `json:"content"`
@@ -45,17 +41,13 @@ type MainResult struct {
 	Positions []int    `json:"positions"`
 	Engines   []string `json:"engines"`
 
-	// These fields exist in the MainResult base; keep them so downstream
-	// callers can generate richer output later.
 	OpenGroup  bool `json:"open_group"`
 	CloseGroup bool `json:"close_group"`
 
-	// parsed_url is emitted as a tuple; we preserve it as-is.
 	ParsedURL any `json:"parsed_url"`
 }
 
 func (mr *MainResult) UnmarshalJSON(data []byte) error {
-	// Preserve the full object.
 	dec := json.NewDecoder(bytes.NewReader(data))
 	dec.UseNumber()
 
@@ -66,7 +58,6 @@ func (mr *MainResult) UnmarshalJSON(data []byte) error {
 
 	mr.raw = m
 
-	// Fill the typed/common fields (best-effort; don't fail if types differ).
 	mr.Template = stringOrEmpty(m["template"])
 	mr.Title = stringOrEmpty(m["title"])
 	mr.Content = stringOrEmpty(m["content"])
@@ -104,12 +95,10 @@ func (mr *MainResult) UnmarshalJSON(data []byte) error {
 }
 
 func (mr MainResult) MarshalJSON() ([]byte, error) {
-	// If we came from upstream JSON, preserve all keys exactly.
 	if mr.raw != nil {
 		return json.Marshal(mr.raw)
 	}
 
-	// Otherwise, marshal the known fields.
 	m := map[string]any{
 		"template":  mr.Template,
 		"title":     mr.Title,

internal/contracts/types.go

@@ -20,18 +20,15 @@ package contracts
 type OutputFormat string
 
 const (
-	FormatHTML OutputFormat = "html" // accepted for compatibility (not yet implemented)
+	FormatHTML OutputFormat = "html" // accepted for compatibility
 	FormatJSON OutputFormat = "json"
 	FormatCSV  OutputFormat = "csv"
 	FormatRSS  OutputFormat = "rss"
 )
 
 type SearchRequest struct {
-	// Format is what the client requested via `format=...`.
-	Format OutputFormat
-
-	Query string
-
+	Format     OutputFormat
+	Query      string
 	Pageno     int
 	Safesearch int
 	TimeRange  *string
@@ -39,16 +36,14 @@ type SearchRequest struct {
 	TimeoutLimit *float64
 	Language     string
 
-	// Engines and categories are used for deciding which engines run locally vs are proxied.
-	// For now, engines can be supplied directly via the `engines` form parameter.
+	// Engines and categories decide which engines run locally vs proxy to upstream.
 	Engines    []string
 	Categories []string
 
 	// EngineData matches the `engine_data-<engine>-<key>=<value>` parameters.
 	EngineData map[string]map[string]string
 
-	// AccessToken is an optional request token used to gate paid/limited engines.
-	// It is not part of the upstream JSON schema; it only influences local engines.
+	// AccessToken gates paid/limited engines. Not part of upstream JSON schema.
 	AccessToken string
 }