From 7823d676371be95d66c539cfc8411e4f59d87b0c Mon Sep 17 00:00:00 2001 From: Maxim Lebedev Date: Sun, 25 Dec 2016 08:10:55 +0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=93=20More=20docs=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- account.go | 58 +++++++++++++++++++++----------------- content.go | 3 +- page.go | 79 ++++++++++++++++++++++++++++------------------------ telegraph.go | 72 ++++++++++++++++++++++++----------------------- 4 files changed, 113 insertions(+), 99 deletions(-) diff --git a/account.go b/account.go index 6694943..6f9d991 100644 --- a/account.go +++ b/account.go @@ -7,23 +7,25 @@ import ( "strings" ) -// CreateAccount create a new Telegraph account. Most users only need one account, but this can be -// useful for channel administrators who would like to keep individual author names and profile -// links for each of their channels. On success, returns an Account object with the regular fields -// and an additional access_token field. +// CreateAccount create a new Telegraph account. Most users only need one +// account, but this can be useful for channel administrators who would like +// to keep individual author names and profile links for each of their +// channels. On success, returns an Account object with the regular fields and +// an additional access_token field. func CreateAccount(shortName string, authorName string, authorURL string) (*Account, error) { var args fasthttp.Args - // Required. Account name, helps users with several accounts remember which they are currently - // using. Displayed to the user above the "Edit/Publish" button on Telegra.ph, other users - // don't see this name. - args.Add("short_name", shortName) + // Account name, helps users with several accounts remember which they are + // currently using. Displayed to the user above the "Edit/Publish" button + // on Telegra.ph, other users don't see this name. + args.Add("short_name", shortName) // required // Default author name used when creating new articles. args.Add("author_name", authorName) - // Default profile link, opened when users click on the author's name below the title. Can be - // any link, not necessarily to a Telegram profile or channel. + // Default profile link, opened when users click on the author's name + // below the title. Can be any link, not necessarily to a Telegram profile + // or channel. args.Add("author_url", authorURL) url := fmt.Sprintf(APIEndpoint, "createAccount") @@ -40,13 +42,14 @@ func CreateAccount(shortName string, authorName string, authorURL string) (*Acco return &resp, nil } -// EditAccountInfo update information about a Telegraph account. Pass only the parameters that you -// want to edit. On success, returns an Account object with the default fields. +// EditAccountInfo update information about a Telegraph account. Pass only the +// parameters that you want to edit. On success, returns an Account object +// with the default fields. func (account *Account) EditAccountInfo(update *Account) (*Account, error) { var args fasthttp.Args - // Required. Access token of the Telegraph account. - args.Add("access_token", account.AccessToken) + // Access token of the Telegraph account. + args.Add("access_token", account.AccessToken) // required // New account name. args.Add("short_name", update.ShortName) @@ -54,8 +57,9 @@ func (account *Account) EditAccountInfo(update *Account) (*Account, error) { // New default author name used when creating new articles. args.Add("author_name", update.AuthorName) - // New default profile link, opened when users click on the author's name below the title. Can - // be any link, not necessarily to a Telegram profile or channel. + // New default profile link, opened when users click on the author's name + // below the title. Can be any link, not necessarily to a Telegram profile + // or channel. args.Add("author_url", update.AuthorURL) url := fmt.Sprintf(APIEndpoint, "editAccountInfo") @@ -72,15 +76,16 @@ func (account *Account) EditAccountInfo(update *Account) (*Account, error) { return &resp, nil } -// GetAccountInfo get information about a Telegraph account. Returns an Account object on success. +// GetAccountInfo get information about a Telegraph account. Returns an +// Account object on success. func (account *Account) GetAccountInfo(fields []string) (*Account, error) { var args fasthttp.Args - // Required. Access token of the Telegraph account. - args.Add("access_token", account.AccessToken) + // Access token of the Telegraph account. + args.Add("access_token", account.AccessToken) // required - // List of account fields to return. Available fields: short_name, author_name, author_url, - // auth_url, page_count. + // List of account fields to return. Available fields: short_name, + // author_name, author_url, auth_url, page_count. args.Add("fields", fmt.Sprintf(`["%s"]`, strings.Join(fields, `","`))) url := fmt.Sprintf(APIEndpoint, "getAccountInfo") @@ -97,14 +102,15 @@ func (account *Account) GetAccountInfo(fields []string) (*Account, error) { return &resp, nil } -// RevokeAccessToken revoke access_token and generate a new one, for example, if the user would -// like to reset all connected sessions, or you have reasons to believe the token was compromised. -// On success, returns an Account object with new access_token and auth_url fields. +// RevokeAccessToken revoke access_token and generate a new one, for example, +// if the user would like to reset all connected sessions, or you have reasons +// to believe the token was compromised. On success, returns an Account object +// with new access_token and auth_url fields. func (account *Account) RevokeAccessToken() (*Account, error) { var args fasthttp.Args - // Required. Access token of the Telegraph account. - args.Add("access_token", account.AccessToken) + // Access token of the Telegraph account. + args.Add("access_token", account.AccessToken) // required url := fmt.Sprintf(APIEndpoint, "revokeAccessToken") body, err := request(url, &args) diff --git a/content.go b/content.go index 5630b10..6678525 100644 --- a/content.go +++ b/content.go @@ -39,7 +39,8 @@ var availableAttributes = map[string]bool{ "src": true, } -// ContentFormat transforms data to a DOM-based format to represent the content of the page. +// ContentFormat transforms data to a DOM-based format to represent the +// content of the page. func ContentFormat(data interface{}) ([]Node, error) { var doc html.Node switch dst := data.(type) { diff --git a/page.go b/page.go index a556e23..f5d1521 100644 --- a/page.go +++ b/page.go @@ -11,11 +11,11 @@ import ( func (account *Account) CreatePage(page *Page, returnContent bool) (*Page, error) { var args fasthttp.Args - // Required. Access token of the Telegraph account. - args.Add("access_token", account.AccessToken) + // Access token of the Telegraph account. + args.Add("access_token", account.AccessToken) // required - // Required. Page title. - args.Add("title", page.Title) + // Page title. + args.Add("title", page.Title) // required if page.AuthorName != "" { // Author name, displayed below the article's title. @@ -23,8 +23,9 @@ func (account *Account) CreatePage(page *Page, returnContent bool) (*Page, error } if page.AuthorURL != "" { - // Profile link, opened when users click on the author's name below the title. Can be any - // link, not necessarily to a Telegram profile or channel. + // Profile link, opened when users click on the author's name below + // the title. Can be any link, not necessarily to a Telegram profile + // or channel. args.Add("author_url", page.AuthorURL) } @@ -36,8 +37,8 @@ func (account *Account) CreatePage(page *Page, returnContent bool) (*Page, error return nil, err } - // Required. Content of the page. - args.Add("content", string(content)) + // Content of the page. + args.Add("content", string(content)) // required url := fmt.Sprintf(APIEndpoint, "createPage") body, err := request(url, &args) @@ -53,39 +54,41 @@ func (account *Account) CreatePage(page *Page, returnContent bool) (*Page, error return &resp, nil } -// EditPage edit an existing Telegraph page. On success, returns a Page object. -func (account *Account) EditPage(page *Page, returnContent bool) (*Page, error) { +// EditPage edit an existing Telegraph page. On success, returns a Page +// object. +func (account *Account) EditPage(update *Page, returnContent bool) (*Page, error) { var args fasthttp.Args - // Required. Access token of the Telegraph account. - args.Add("access_token", account.AccessToken) + // Access token of the Telegraph account. + args.Add("access_token", account.AccessToken) // required - // Required. Page title. - args.Add("title", page.Title) + // Page title. + args.Add("title", update.Title) // required - if page.AuthorName != "" { + if update.AuthorName != "" { // Author name, displayed below the article's title. - args.Add("author_name", page.AuthorName) + args.Add("author_name", update.AuthorName) } - if page.AuthorURL != "" { - // Profile link, opened when users click on the author's name below the title. Can be any - // link, not necessarily to a Telegram profile or channel. - args.Add("author_url", page.AuthorURL) + if update.AuthorURL != "" { + // Profile link, opened when users click on the author's name below + // the title. Can be any link, not necessarily to a Telegram profile + // or channel. + args.Add("author_url", update.AuthorURL) } // If true, a content field will be returned in the Page object. args.Add("return_content", strconv.FormatBool(returnContent)) - content, err := json.Marshal(page.Content) + content, err := json.Marshal(update.Content) if err != nil { return nil, err } - // Required. Content of the page. - args.Add("content", string(content)) + // Content of the page. + args.Add("content", string(content)) // required - url := fmt.Sprintf(PathEndpoint, "editPage", page.Path) + url := fmt.Sprintf(PathEndpoint, "editPage", update.Path) body, err := request(url, &args) if err != nil { return nil, err @@ -120,13 +123,13 @@ func GetPage(path string, returnContent bool) (*Page, error) { return &resp, nil } -// GetPageList get a list of pages belonging to a Telegraph account. Returns a PageList object, -// sorted by most recently created pages first. +// GetPageList get a list of pages belonging to a Telegraph account. Returns +// a PageList object, sorted by most recently created pages first. func (account *Account) GetPageList(offset int, limit int) (*PageList, error) { var args fasthttp.Args - // Required. Access token of the Telegraph account. - args.Add("access_token", account.AccessToken) + // Access token of the Telegraph account. + args.Add("access_token", account.AccessToken) // required // Sequential number of the first page to be returned. args.Add("offset", strconv.Itoa(offset)) @@ -148,31 +151,33 @@ func (account *Account) GetPageList(offset int, limit int) (*PageList, error) { return &resp, nil } -// GetViews get the number of views for a Telegraph article. By default, the total number of page -// views will be returned. Returns a PageViews object on success. +// GetViews get the number of views for a Telegraph article. By default, the +// total number of page views will be returned. Returns a PageViews object +// on success. func GetViews(path string, hour int, day int, month int, year int) (*PageViews, error) { var args fasthttp.Args if hour > -1 { - // If passed, the number of page views for the requested hour will be returned. + // If passed, the number of page views for the requested hour will + // be returned. args.Add("hour", strconv.Itoa(hour)) } if day > 0 { - // Required if hour is passed. If passed, the number of page views for the requested - // day will be returned. + // Required if hour is passed. If passed, the number of page views + // for the requested day will be returned. args.Add("day", strconv.Itoa(day)) } if month > 0 { - // Required if day is passed. If passed, the number of page views for the - // requested month will be returned. + // Required if day is passed. If passed, the number of page views + // for the requested month will be returned. args.Add("month", strconv.Itoa(month)) } if year > 0 { - // Required if month is passed. If passed, the number of page views for the - // requested year will be returned. + // Required if month is passed. If passed, the number of page views + // for the requested year will be returned. args.Add("year", strconv.Itoa(year)) } diff --git a/telegraph.go b/telegraph.go index 33e3de0..3156f0d 100644 --- a/telegraph.go +++ b/telegraph.go @@ -1,3 +1,5 @@ +// Package telegraph has functions and types used for interacting with the +// Telegraph API. package telegraph import ( @@ -19,14 +21,14 @@ const ( type ( // Account represents a Telegraph account. Account struct { - // Optional. Only returned by the createAccount and revokeAccessToken - // method. Access token of the Telegraph account. - AccessToken string `json:"access_token"` + // Only returned by the createAccount and revokeAccessToken method. + // Access token of the Telegraph account. + AccessToken string `json:"access_token"` // optional - // Optional. URL to authorize a browser on telegra.ph and connect it to - // a Telegraph account. This URL is valid for only one use and for 5 + // URL to authorize a browser on telegra.ph and connect it to a + // Telegraph account. This URL is valid for only one use and for 5 // minutes only. - AuthURL string `json:"auth_url"` + AuthURL string `json:"auth_url"` // optional // Account name, helps users with several accounts remember which they // are currently using. Displayed to the user above the "Edit/Publish" @@ -41,12 +43,12 @@ type ( // channel. AuthorURL string `json:"author_url"` - // Optional. Number of pages belonging to the Telegraph account. - PageCount int `json:"page_count"` + // Number of pages belonging to the Telegraph account. + PageCount int `json:"page_count"` // optional } - // PageList represents a list of Telegraph articles belonging to an account. - // Most recently created articles first. + // PageList represents a list of Telegraph articles belonging to an + // account. Most recently created articles first. PageList struct { // Total number of pages belonging to the target Telegraph account. TotalCount int `json:"total_count"` @@ -69,26 +71,26 @@ type ( // Description of the page. Description string `json:"description"` - // Optional. Name of the author, displayed below the title. - AuthorName string `json:"author_name"` + // Name of the author, displayed below the title. + AuthorName string `json:"author_name"` // optional - // Optional. Profile link, opened when users click on the author's name - // below the title. Can be any link, not necessarily to a Telegram - // profile or channel. - AuthorURL string `json:"author_url"` + // Profile link, opened when users click on the author's name below + // the title. Can be any link, not necessarily to a Telegram profile + // or channel. + AuthorURL string `json:"author_url"` // optional - // Optional. Image URL of the page. - ImageURL string `json:"image_url"` + // Image URL of the page. + ImageURL string `json:"image_url"` // optional - // Optional. Content of the page. - Content []Node `json:"content"` + // Content of the page. + Content []Node `json:"content"` // optional // Number of page views for the page. Views int `json:"views"` - // Optional. Only returned if access_token passed. True, if the target - // Telegraph account can edit the page. - CanEdit bool `json:"can_edit"` + // Only returned if access_token passed. True, if the target Telegraph + // account can edit the page. + CanEdit bool `json:"can_edit"` // optional } // PageViews represents the number of page views for a Telegraph article. @@ -103,25 +105,25 @@ type ( // NodeElement represents a DOM element node. NodeElement struct { - // Name of the DOM element. Available tags: a, aside, b, blockquote, br, - // code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, ol, p, - // pre, s, strong, u, ul, video. + // Name of the DOM element. Available tags: a, aside, b, blockquote, + // br, code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, + // ol, p, pre, s, strong, u, ul, video. Tag string `json:"tag"` - // Optional. Attributes of the DOM element. Key of object represents - // name of attribute, value represents value of attribute. Available + // Attributes of the DOM element. Key of object represents name of + // attribute, value represents value of attribute. Available // attributes: href, src. - Attrs map[string]string `json:"attrs"` + Attrs map[string]string `json:"attrs"` // optional - // Optional. List of child nodes for the DOM element. - Children []Node `json:"children"` + // List of child nodes for the DOM element. + Children []Node `json:"children"` // optional } // Response represents a response from the Telegram API with the result - // stored raw. If ok equals true, the request was successful, and the result - // of the query can be found in the result field. In case of an unsuccessful - // request, ok equals false, and the error is explained in the error field - // (e.g. SHORT_NAME_REQUIRED). + // stored raw. If ok equals true, the request was successful, and the + // result of the query can be found in the result field. In case of an + // unsuccessful request, ok equals false, and the error is explained in + // the error field (e.g. SHORT_NAME_REQUIRED). Response struct { Ok bool `json:"ok"` Error string `json:"error"`