doc

README

doc

This module provides an API to programatically search the documentation of Go modules.

Usage

To import and use, go get github.com/hhhapz/doc

s := doc.New(http.DefaultClient, godocs.Parser, opts...) // or pkgsite.Parser
pkg, err := s.Search(context.TODO(), "bytes")

// use pkg

Options (opts...)

Currently there are two available options:

doc.MaintainCase()

By default, the maps in the Package struct will have lower case keys:

• Package.Functions
• Package.Types
• Package.Types.TypeFunctions
• Package.Types.Methods

When enabling MaintainCase, the keys to all of these functions will be retained to their true case.

doc.UserAgent(string)

UserAgent will allow you to change the UA agent for all requests to the package sites. by default it will link to this repository.

---

Caching packages

The doc package also has a basic caching implementation that stores results in an in-memory map.

s := doc.New(http.DefaultClient, godocs.Parser) // or pkgsite.Parser
cs := doc.WithCache(s)

pkg, err := cs.Search(context.TODO(), "bytes")

// Cached results
pkg, err := cs.Search(context.TODO(), "bytes")

---

This package relies on https://godocs.io. It is planned to add a parser for pkgsite as well.

Documentation

Index

• type CachedPackage
• type CachedSearcher
  • func NewCachedSearcher(parser Parser, opts ...SearchOption) CachedSearcher
• type Comment
  • func (c Comment) HTML() string
  • func (c Comment) Markdown() string
  • func (c Comment) Text() string
• type Example
• type Function
• type Heading
  • func (h Heading) HTML() string
  • func (h Heading) Markdown() string
  • func (h Heading) Text() string
• type InvalidStatusError
  • func (err InvalidStatusError) Error() string
• type Method
• type Note
• type Package
• type Paragraph
  • func (p Paragraph) HTML() string
  • func (p Paragraph) Markdown() string
  • func (p Paragraph) Text() string
• type Parser
• type Pre
  • func (pre Pre) HTML() string
  • func (pre Pre) Markdown() string
  • func (pre Pre) Text() string
• type SearchOption
  • func MaintainCase() SearchOption
  • func UserAgent(agent string) SearchOption
  • func WithClient(client *http.Client) SearchOption
  • func WithDuplicateTypeFuncs() SearchOption
• type Searcher
  • func NewSearcher(parser Parser, opts ...SearchOption) Searcher
• type Type
• type Variable

Types

type CachedPackage

type CachedPackage struct {
	Package
	Created time.Time
	Updated time.Time
}

type CachedSearcher

type CachedSearcher interface {
	Searcher
	// WithCache gives access to modify and update the contents of the internal cache.
	WithCache(func(cache map[string]*CachedPackage))
}

func NewCachedSearcher

func NewCachedSearcher(parser Parser, opts ...SearchOption) CachedSearcher

type Comment

type Comment []Note

func (Comment) HTML

func (c Comment) HTML() string

func (Comment) Markdown

func (c Comment) Markdown() string

func (Comment) Text

func (c Comment) Text() string

type Example

type Example struct {
	Name   string
	Code   string
	Output string
}

type Function

type Function struct {
	Name      string    `json:"name"`
	Signature string    `json:"signature"`
	Comment   Comment   `json:"comment"`
	Examples  []Example `json:"examples"`
}

type Heading

type Heading string

func (Heading) HTML

func (h Heading) HTML() string

func (Heading) Markdown

func (h Heading) Markdown() string

func (Heading) Text

func (h Heading) Text() string

type InvalidStatusError

type InvalidStatusError int

InvalidStatusError indicates that the request to the godocs.io was not successful. The value is the status that was returned from the page instead.

func (InvalidStatusError) Error

func (err InvalidStatusError) Error() string

Error satisfies the error interface.

type Method

type Method struct {
	For string `json:"for"`
	Function
}

type Note

type Note interface {
	Text() string
	HTML() string
	Markdown() string
}

type Package

type Package struct {
	URL      string    `json:"url"`
	Name     string    `json:"name"`
	Overview Comment   `json:"overview"`
	Examples []Example `json:"examples"`

	Constants []Variable `json:"constants"`
	Variables []Variable `json:"variables"`

	ConstantMap map[string]Variable `json:"constant_map"`
	VariableMap map[string]Variable `json:"variable_map"`

	Functions map[string]Function `json:"functions"`
	Types     map[string]Type     `json:"types"`

	Subpackages []string `json:"subpackages"`
}

type Paragraph

type Paragraph string

func (Paragraph) HTML

func (p Paragraph) HTML() string

func (Paragraph) Markdown

func (p Paragraph) Markdown() string

func (Paragraph) Text

func (p Paragraph) Text() string

type Parser

type Parser interface {
	URL(module string) (full string)
	Parse(document *goquery.Document, useCase, dupeTypeFuncs bool) (Package, error)
}

Parser is the interface that package site parsers implement.

type Pre

type Pre string

func (Pre) HTML

func (pre Pre) HTML() string

func (Pre) Markdown

func (pre Pre) Markdown() string

func (Pre) Text

func (pre Pre) Text() string

type SearchOption

type SearchOption = func(s *httpSearcher)

func MaintainCase

func MaintainCase() SearchOption

func UserAgent

func UserAgent(agent string) SearchOption

func WithClient

func WithClient(client *http.Client) SearchOption

func WithDuplicateTypeFuncs

func WithDuplicateTypeFuncs() SearchOption

type Searcher

type Searcher interface {
	// Search will find a package with the module name.
	Search(ctx context.Context, module string) (Package, error)
}

func NewSearcher

func NewSearcher(parser Parser, opts ...SearchOption) Searcher

type Type

type Type struct {
	Name      string    `json:"name"`
	Type      string    `json:"type"`
	Signature string    `json:"signature"`
	Comment   Comment   `json:"comment"`
	Examples  []Example `json:"examples"`

	TypeFunctions map[string]Function `json:"type_functions"`
	Methods       map[string]Method   `json:"methods"`
}

type Variable

type Variable struct {
	Name      string  `json:"name"`
	Signature string  `json:"signature"`
	Comment   Comment `json:"comment"`
}