feat: add docs and fix types

- interface{} -> *string in MethodList

Author: kkweon

client.go

@@ -22,15 +22,15 @@ type ClientOption func(*Client)
 func WithAPIToken(apiToken string) ClientOption {
 	return func(client *Client) {
 		client.apiToken = apiToken
-		client.HTTPClient.Transport = transport.NewTransportWithAuthHeader(apiToken)
+		client.httpClient.Transport = transport.NewTransportWithAuthHeader(apiToken)
 	}
 }
 
 // NewClient creates a Client object.
 func NewClient(opts ...ClientOption) *Client {
 	defaultClient := &Client{
-		BaseURL: BaseURL,
-		HTTPClient: &http.Client{
+		baseURL: BaseURL,
+		httpClient: &http.Client{
 			Timeout: time.Minute,
 		},
 	}
@@ -43,11 +43,13 @@ func NewClient(opts ...ClientOption) *Client {
 }
 
 type Client struct {
-	BaseURL    string
-	HTTPClient *http.Client
+	baseURL    string
+	httpClient *http.Client
 	apiToken   string
 }
 
+// GetPaperIDFromPaperTitle generates a paper ID from paper title.
+// WARNING: This function does not cover all cases.
 func GetPaperIDFromPaperTitle(paperTitle string) string {
 	return strings.ToLower(whiteSpaceRegexp.ReplaceAllString(paperTitle, "-"))
 }

client_test.go

@@ -28,14 +28,14 @@ func TestWithAPIToken(t *testing.T) {
 	emptyRequest, err := http.NewRequest(http.MethodGet, server.URL, nil)
 
 	assert.NoError(t, err)
-	_, err = c.HTTPClient.Transport.RoundTrip(emptyRequest)
+	_, err = c.httpClient.Transport.RoundTrip(emptyRequest)
 	assert.NoError(t, err)
 	assert.Equal(t, "Token MY_TOKEN", emptyRequest.Header.Get("Authorization"))
 }
 
 func TestTransportIsNotProvidedWhenNoAPIIsProvided(t *testing.T) {
 	c := NewClient()
-	assert.Nil(t, c.HTTPClient.Transport)
+	assert.Nil(t, c.httpClient.Transport)
 }
 
 func ExampleGetPaperIDFromPaperTitle() {

models/methods.go

@@ -10,8 +10,8 @@ type Method struct {
 
 // MethodList represents methods used in the paper.
 type MethodList struct {
-	Count    int         `json:"count"`
-	Next     interface{} `json:"next"`
-	Previous interface{} `json:"previous"`
-	Results  []*Method   `json:"results"`
+	Count    int       `json:"count"`
+	Next     *string   `json:"next"`
+	Previous *string   `json:"previous"`
+	Results  []*Method `json:"results"`
 }

models/results.go

@@ -1,5 +1,6 @@
 package models
 
+// Result is the evaluation result from a paper.
 type Result struct {
 	ID                 string            `json:"id"`
 	BestRank           *int              `json:"best_rank"`

models/yyyymmdd.go

@@ -6,6 +6,7 @@ import (
 	"time"
 )
 
+// YyyyMmDdDashed is the special date type to parse YYYY-MM-DD format.
 type YyyyMmDdDashed time.Time
 
 func (y *YyyyMmDdDashed) UnmarshalJSON(bytes []byte) error {

models/yyyymmdd_test.go

@@ -2,7 +2,6 @@ package models
 
 import (
 	"testing"
-	"time"
 )
 
 func TestYyyyMmDdDashed_UnmarshalJSON(t *testing.T) {
@@ -17,15 +16,15 @@ func TestYyyyMmDdDashed_UnmarshalJSON(t *testing.T) {
 	}{
 		{
 			name:     "2021-05-01 is a valid YyyyMmDdDashed type",
-			expected: YyyyMmDdDashed(time.Date(2021, 5, 1, 0, 0, 0, 0, time.UTC)),
+			expected: NewYyyyMmDdDashed(2021, 5, 1),
 			args: args{
 				inputDateString: "2021-05-01",
 			},
 			wantErr: false,
 		},
 		{
 			name:     "20210501 is NOT a valid YyyyMmDdDashed type",
-			expected: YyyyMmDdDashed(time.Date(2021, 5, 1, 0, 0, 0, 0, time.UTC)),
+			expected: NewYyyyMmDdDashed(2021, 5, 1),
 			args: args{
 				inputDateString: "20210501",
 			},

paper_get.go

@@ -9,8 +9,8 @@ import (
 
 // PaperGet returns a single paper. Note that paperID is hyphen cased (e.g., generative-adversarial-networks).
 func (c *Client) PaperGet(paperID string) (*models.Paper, error) {
-	paperGetURL := fmt.Sprintf("%s/papers/%s/", c.BaseURL, url.QueryEscape(paperID))
-	response, err := c.HTTPClient.Get(paperGetURL)
+	paperGetURL := fmt.Sprintf("%s/papers/%s/", c.baseURL, url.QueryEscape(paperID))
+	response, err := c.httpClient.Get(paperGetURL)
 	if err != nil {
 		return nil, err
 	}

paper_list.go

@@ -7,10 +7,11 @@ import (
 	"net/url"
 )
 
+// PaperList returns multiple papers.
 func (c *Client) PaperList(params PaperListParams) (*models.PaperList, error) {
-	papersListURL := c.BaseURL + "/papers?" + params.Build()
+	papersListURL := c.baseURL + "/papers?" + params.build()
 
-	response, err := c.HTTPClient.Get(papersListURL)
+	response, err := c.httpClient.Get(papersListURL)
 	if err != nil {
 		return nil, err
 	}
@@ -25,19 +26,25 @@ func (c *Client) PaperList(params PaperListParams) (*models.PaperList, error) {
 	return &paperListResult, nil
 }
 
+// PaperListParams is the parameter for PaperList method.
 type PaperListParams struct {
+	// Query to search papers (default: "")
+	// If empty, it returns all papers.
 	Query string
-	Page  int
+	// Page is the number of page to search (default: 1)
+	Page int
+	// Limit returns how many papers are returned in a single response.
 	Limit int
 }
 
-func (p PaperListParams) Build() string {
+func (p PaperListParams) build() string {
 	if p.Query == "" {
 		return fmt.Sprintf("items_per_page=%d&page=%d", p.Limit, p.Page)
 	}
 	return fmt.Sprintf("q=%s&items_per_page=%d&page=%d", url.QueryEscape(p.Query), p.Limit, p.Page)
 }
 
+// PaperListParamsDefault returns the default PaperListParams.
 func PaperListParamsDefault() PaperListParams {
 	return PaperListParams{
 		Query: "",

paper_method_list.go

@@ -8,8 +8,9 @@ import (
 	"net/url"
 )
 
+// PaperMethodList returns the methods used in the given paper.
 func (c *Client) PaperMethodList(paperID string) (*models.MethodList, error) {
-	pURL := fmt.Sprintf("%s/papers/%s/methods", c.BaseURL, url.QueryEscape(paperID))
+	pURL := fmt.Sprintf("%s/papers/%s/methods", c.baseURL, url.QueryEscape(paperID))
 	response, err := http.Get(pURL)
 	if err != nil {
 		return nil, err

paper_repository_list.go

@@ -7,9 +7,10 @@ import (
 	"net/url"
 )
 
+// PaperRepositoryList returns repositories related to the given paper.
 func (c *Client) PaperRepositoryList(paperID string) (*models.RepositoryList, error) {
-	paperURL := fmt.Sprintf("%s/papers/%s/repositories", c.BaseURL, url.QueryEscape(paperID))
-	response, err := c.HTTPClient.Get(paperURL)
+	paperURL := fmt.Sprintf("%s/papers/%s/repositories", c.baseURL, url.QueryEscape(paperID))
+	response, err := c.httpClient.Get(paperURL)
 	if err != nil {
 		return nil, err
 	}

paper_result_list.go

@@ -7,10 +7,11 @@ import (
 	"net/url"
 )
 
+// PaperResultList returns the evaluation results of the paper.
 func (c *Client) PaperResultList(paperID string) (*models.ResultList, error) {
-	pURL := fmt.Sprintf("%s/papers/%s/results", c.BaseURL, url.QueryEscape(paperID))
+	pURL := fmt.Sprintf("%s/papers/%s/results", c.baseURL, url.QueryEscape(paperID))
 
-	resp, err := c.HTTPClient.Get(pURL)
+	resp, err := c.httpClient.Get(pURL)
 	if err != nil {
 		return nil, err
 	}

paper_task_list.go

@@ -7,9 +7,10 @@ import (
 	"net/url"
 )
 
+// PaperTaskList returns tasks (an area of research) for the given paper.
 func (c *Client) PaperTaskList(paperID string) (*models.TaskList, error) {
-	pURL := fmt.Sprintf("%s/papers/%s/tasks/", c.BaseURL, url.QueryEscape(paperID))
-	resp, err := c.HTTPClient.Get(pURL)
+	pURL := fmt.Sprintf("%s/papers/%s/tasks/", c.baseURL, url.QueryEscape(paperID))
+	resp, err := c.httpClient.Get(pURL)
 	if err != nil {
 		return nil, err
 	}