docc

package

v0.19.0 Latest Latest Go to latest Published: Aug 11, 2026 License: MIT Imports: 12 Imported by: 0

Documentation ¶

Overview ¶

Package docc models Apple's DocC "render JSON" (the structured data behind every developer.apple.com/documentation page) and projects it into the Objective-C variant so symbol titles read as ObjC selectors.

Index ¶

Variables
func ApplyPatch(doc any, ops []PatchOp) (any, error)
func PageURL(symbolPath string) string
func RenderURL(symbolPath string) string
type BlockElement
type Client
- func NewClient(cacheDir string, minDelay time.Duration) *Client
- func (c *Client) FetchObjC(symbolPath string) (*RenderNode, error)
type ContentSection
type Fragment
type Identifier
type Inline
type Metadata
type PatchOp
type Reference
- func (r Reference) AbstractText(refs map[string]Reference) string
- func (r Reference) HasMethodFragment() bool
- func (r Reference) IsClassMethod() bool
type RenderNode
- func ParseObjC(data []byte) (*RenderNode, error)
- func (n *RenderNode) Abstract() string
- func (n *RenderNode) Discussion() string
type Trait
type VariantOverride

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrNotFound = errors.New("doc page not found")

ErrNotFound is returned for a 404 — a symbol with no published page.

Functions ¶

func ApplyPatch ¶

func ApplyPatch(doc any, ops []PatchOp) (any, error)

ApplyPatch applies an RFC-6902 patch to a decoded JSON document (a map[string]any / []any tree) in place where possible, returning the new root. DocC uses this mechanism in variantOverrides to project the base (Swift) render JSON into the Objective-C view, which is where ObjC selectors live.

func PageURL ¶

func PageURL(symbolPath string) string

PageURL builds the human-readable documentation URL for a symbol path.

func RenderURL ¶

func RenderURL(symbolPath string) string

RenderURL builds the render-JSON URL for a symbol path (already lowercased segments joined by "/", e.g. "foundation/nsstring").

Types ¶

type BlockElement ¶

type BlockElement struct {
	Type          string   `json:"type"`
	Text          string   `json:"text"`
	InlineContent []Inline `json:"inlineContent"`
}

BlockElement is a block-level content node (paragraph, heading, …).

type Client ¶

type Client struct {
	HTTP      *http.Client
	CacheDir  string        // when non-empty, responses are cached here
	MinDelay  time.Duration // minimum gap between live requests
	UserAgent string
	MaxRetry  int
	// contains filtered or unexported fields
}

Client fetches DocC render JSON with a polite rate limit, retries, and an on-disk response cache so re-runs (and tests) avoid the network.

func NewClient ¶

func NewClient(cacheDir string, minDelay time.Duration) *Client

NewClient returns a Client with sensible defaults.

func (*Client) FetchObjC ¶

func (c *Client) FetchObjC(symbolPath string) (*RenderNode, error)

FetchObjC fetches the render JSON for symbolPath and returns the Objective-C-projected RenderNode. Returns ErrNotFound on a 404.

type ContentSection ¶

type ContentSection struct {
	Kind    string         `json:"kind"`
	Content []BlockElement `json:"content"`
}

ContentSection is a primary-content block; we read the "content" kind for the Discussion/Overview prose.

type Fragment ¶

type Fragment struct {
	Kind string `json:"kind"`
	Text string `json:"text"`
}

Fragment is one token of a symbol's declaration. In the ObjC variant the first fragment of a method is "- " (instance) or "+ " (class).

type Identifier ¶

type Identifier struct {
	URL string `json:"url"`
}

Identifier is the symbol's canonical doc:// URI.

type Inline ¶

type Inline struct {
	Type          string   `json:"type"`
	Text          string   `json:"text"`
	Code          string   `json:"code"`
	Identifier    string   `json:"identifier"`
	InlineContent []Inline `json:"inlineContent"`
}

Inline is an inline content node (text, codeVoice, reference, emphasis, …).

type Metadata ¶

type Metadata struct {
	Title      string `json:"title"`
	Role       string `json:"role"`
	SymbolKind string `json:"symbolKind"`
}

Metadata holds the symbol's own identity.

type PatchOp ¶

type PatchOp struct {
	Op    string `json:"op"`
	Path  string `json:"path"`
	Value any    `json:"value,omitempty"`
}

PatchOp is a single RFC-6902 JSON-Patch operation as it appears in a DocC variantOverrides entry. Only the operations DocC actually emits (add, replace, remove) are supported.

type Reference ¶

type Reference struct {
	Type       string     `json:"type"`
	Title      string     `json:"title"`
	Identifier string     `json:"identifier"`
	Abstract   []Inline   `json:"abstract"`
	Fragments  []Fragment `json:"fragments"`
	Role       string     `json:"role"`
	Kind       string     `json:"kind"`
	URL        string     `json:"url"`
}

Reference is an entry in the references map: a symbol linked from this page, including the page's own child members (methods, properties, enum cases).

func (Reference) AbstractText ¶

func (r Reference) AbstractText(refs map[string]Reference) string

AbstractText returns this reference's summary as plain text.

func (Reference) HasMethodFragment ¶

func (r Reference) HasMethodFragment() bool

HasMethodFragment reports whether this reference looks like an ObjC method declaration (leading "- " or "+ " fragment), distinguishing methods from properties/constants that share the references map.

func (Reference) IsClassMethod ¶

func (r Reference) IsClassMethod() bool

IsClassMethod reports whether this reference's ObjC declaration is a class method ("+ " leading fragment) rather than an instance method ("- ").

type RenderNode ¶

type RenderNode struct {
	AbstractInline         []Inline             `json:"abstract"`
	PrimaryContentSections []ContentSection     `json:"primaryContentSections"`
	References             map[string]Reference `json:"references"`
	Metadata               Metadata             `json:"metadata"`
	Identifier             Identifier           `json:"identifier"`
	VariantOverrides       []VariantOverride    `json:"variantOverrides"`
}

RenderNode is the subset of a DocC render-JSON document we consume.

func ParseObjC ¶

func ParseObjC(data []byte) (*RenderNode, error)

ParseObjC decodes DocC render JSON and projects it into the Objective-C variant by applying the matching variantOverrides JSON-Patch. When no ObjC override is present (Swift-only symbol) the base document is returned as-is.

func (*RenderNode) Abstract ¶

func (n *RenderNode) Abstract() string

Abstract returns the symbol's one-line summary as plain text.

func (*RenderNode) Discussion ¶

func (n *RenderNode) Discussion() string

Discussion returns the symbol's Overview/Discussion paragraphs as plain text, paragraphs separated by blank lines. Non-paragraph blocks are skipped.

type Trait ¶

type Trait struct {
	InterfaceLanguage string `json:"interfaceLanguage"`
}

Trait identifies which interface language a variant override applies to.

type VariantOverride ¶

type VariantOverride struct {
	Traits []Trait   `json:"traits"`
	Patch  []PatchOp `json:"patch"`
}

VariantOverride is one language projection expressed as a JSON-Patch.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL