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

• func MaintainCase() func(configurer)
• func UserAgent(agent string) func(configurer)
• type CachedPackage
• type CachedSearcher
  • func WithCache(s Searcher) *CachedSearcher
  • func (cs *CachedSearcher) Search(ctx context.Context, module string) (Package, error)
  • func (cs *CachedSearcher) WithCache(f func(cache map[string]*CachedPackage))
• type Comment
  • func (c Comment) HTML() string
  • func (c Comment) Markdown() string
  • func (c Comment) Text() string
• type Example
• type Function
• type HTTPSearcher
  • func New(client *http.Client, parser Parser, opts ...func(configurer)) *HTTPSearcher
  • func (h HTTPSearcher) Search(ctx context.Context, module string) (Package, error)
• 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 Searcher
• type Type

Functions

func MaintainCase

func MaintainCase() func(configurer)

func UserAgent

func UserAgent(agent string) func(configurer)

Types

type CachedPackage

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

type CachedSearcher

type CachedSearcher struct {
	// contains filtered or unexported fields
}

func WithCache

func WithCache(s Searcher) *CachedSearcher

func (*CachedSearcher) Search

func (cs *CachedSearcher) Search(ctx context.Context, module string) (Package, error)

func (*CachedSearcher) WithCache

func (cs *CachedSearcher) WithCache(f func(cache map[string]*CachedPackage))

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 HTTPSearcher

type HTTPSearcher struct {
	// contains filtered or unexported fields
}

HTTPSearcher provides an interface to search the godocs package module page. It implements the Searcher interface. A parser must be provided, such as pkgsite.Parser, or godoc.Parser.

HTTPSearcher does not cache results and will do the request every time, even if provided the same module name. If caching is required, the CachedSearcher type.

func New

func New(client *http.Client, parser Parser, opts ...func(configurer)) *HTTPSearcher

func (HTTPSearcher) Search

func (h HTTPSearcher) Search(ctx context.Context, module string) (Package, error)

Search searches godocs for the provided module.

SearchContext is the main workhorse for querying and parsing the http response. The implementation for parsing the document can be found in parse.go

If the page does not respond with a 200 status code, a InvalidStatusError is returned. If the page could not be parsed by GoQuery, the error will be of type Otherwise, issues while parsing the document will of type ParseError, and will contain the selector being parsed, for more context.

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"`

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

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 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 Searcher

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

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"`
}