getdoc

README

getdoc

Documentation extract utilities for Telegram schema using goquery.

Used by gotd/td for embedding documentation to generated code.

Parsed documentation

Parsed documentation for 133 layer is available as 133.json with schema.

Example

Latest schema is embedded to package, so you can just use it:

doc, err := getdoc.Load(133)
if err != nil {
    panic(err)
}
fmt.Printf("Layer %d, constructors: %d\n", doc.Index.Layer, len(doc.Constructors))
// Output:
// Layer 133, constructors: 926

Reference

Please use official documentation, it is for humans, this package is not.

Documentation

Overview

Package getdoc provides a way to transform Telegram TL documentation into machine-readable format.

Index

• Constants
• Variables
• func LayerExists(layer int) bool
• type Category
• type Constructor
  • func ParseConstructor(reader io.Reader) (*Constructor, error)
• type Doc
  • func Extract(ctx context.Context, d Downloader) (*Doc, error)
  • func ExtractLayer(ctx context.Context, layer int, d Downloader) (*Doc, error)
  • func Load(layer int) (*Doc, error)
• type Downloader
• type Error
• type Index
  • func ParseIndex(reader io.Reader) (*Index, error)
• type Method
  • func ParseMethod(reader io.Reader) (*Method, error)
• type ParamDescription
• type Type
  • func ParseType(reader io.Reader) (*Type, error)

Examples

• Load

Constants

const (
	CategoryType        = "type"
	CategoryConstructor = "constructor"
	CategoryMethod      = "method"
)

const LayerLatest = 158

LayerLatest is id of the latest layer.

Variables

var ErrNotFound = errors.New("layer not found")

ErrNotFound means that current package version does not support requested layer.

var Layers = []int{
	121,
	133,
	138,
	139,
	144,
	145,
	155,
	158,
}

Layers is list of supported layers.

Functions

func LayerExists

func LayerExists(layer int) bool

LayerExists returns true if layer is included in package.

Types

type Category

type Category struct {
	Name   string   `json:"name"`
	Values []string `json:"values"`
}

Category index.

type Constructor

type Constructor struct {
	Name        string                      `json:"name"`
	Description []string                    `json:"description,omitempty"`
	Links       []string                    `json:"links,omitempty"`
	Fields      map[string]ParamDescription `json:"fields,omitempty"`
}

Constructor represents constructor documentation.

func ParseConstructor

func ParseConstructor(reader io.Reader) (*Constructor, error)

ParseConstructor parses html documentation from reader and produces Constructor.

type Doc

type Doc struct {
	Index Index `json:"index"`

	Constructors map[string]Constructor `json:"constructors"`
	Types        map[string]Type        `json:"types"`
	Methods      map[string]Method      `json:"methods"`
	Errors       map[string]Error       `json:"errors"`
}

Doc represents full documentation description.

func Extract

func Extract(ctx context.Context, d Downloader) (*Doc, error)

Extract uses Downloader to extract documentation.

func ExtractLayer

func ExtractLayer(ctx context.Context, layer int, d Downloader) (*Doc, error)

ExtractLayer uses Downloader to extract documentation of specified layer.

func Load

func Load(layer int) (*Doc, error)

Load layer documentation.

Example

package main

import (
	"fmt"

	"github.com/gotd/getdoc"
)

func main() {
	layer := 133
	if !getdoc.LayerExists(121) {
		panic("not exists")
	}
	if !getdoc.LayerExists(133) {
		panic("not exists")
	}
	doc, err := getdoc.Load(layer)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Layer %d, constructors: %d\n", doc.Index.Layer, len(doc.Constructors))
}

Output:

Layer 133, constructors: 926

type Downloader

type Downloader interface {
	Get(ctx context.Context, layer int, key string) ([]byte, error)
}

Downloader abstracts documentation fetching.

type Error

type Error struct {
	Code        int    `json:"code"`
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}

Error represent possible error documentation.

type Index

type Index struct {
	Layer      int        `json:"layer"`
	Categories []Category `json:"categories"`
}

Index of schema.

func ParseIndex

func ParseIndex(reader io.Reader) (*Index, error)

ParseIndex parses schema index documentation from reader.

type Method

type Method struct {
	Name        string                      `json:"name"`
	Description []string                    `json:"description,omitempty"`
	Links       []string                    `json:"links,omitempty"`
	Parameters  map[string]ParamDescription `json:"parameters,omitempty"`
	Errors      []Error                     `json:"errors,omitempty"`
	BotCanUse   bool                        `json:"bot_can_use,omitempty"`
}

Method represents method documentation.

func ParseMethod

func ParseMethod(reader io.Reader) (*Method, error)

ParseMethod extracts method documentation from reader.

type ParamDescription

type ParamDescription struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Links       []string `json:"links,omitempty"`
}

type Type

type Type struct {
	Name        string   `json:"name"`
	Description []string `json:"description,omitempty"`
	Links       []string `json:"links,omitempty"`
}

Type represents type (aka class) documentation.

func ParseType

func ParseType(reader io.Reader) (*Type, error)

ParseType parses Type documentation from reader.