Initial pass at documentation (#9)

Author: laconc

dwapi/datasets.go

@@ -26,31 +26,44 @@ type DatasetService struct {
 	client *Client
 }
 
+// AddFilesFromURLs adds files from URLs to a dataset. This method allows files published on the web
+// to be added to a data.world dataset via their URL. This method can also be used to retrieve data
+// via web APIs, with advanced options for HTTP method, request payload and authentication.
+//
+// The source URL will be stored so you can easily update your file anytime it changes via the
+// `Sync now` button on the dataset page or by calling `Dataset.Sync()`.
 func (s *DatasetService) AddFilesFromURLs(owner, datasetid string, body *[]FileCreateRequest) (
 	response SuccessResponse, err error) {
 	return s.client.File.AddFilesFromURLs(owner, datasetid, body)
 }
 
+// AssociateDOI associates a DOI (Digital Object Identifier) with a dataset.
 func (s *DatasetService) AssociateDOI(owner, datasetid, doi string) (response SuccessResponse, err error) {
 	return s.client.DOI.Associate(owner, datasetid, doi)
 }
 
+// AssociateDOIWithVersion associates a DOI (Digital Object Identifier) with a version of a dataset.
 func (s *DatasetService) AssociateDOIWithVersion(owner, datasetid, versionid, doi string) (
 	response SuccessResponse, err error) {
 	return s.client.DOI.AssociateWithVersion(owner, datasetid, versionid, doi)
 }
 
+// Contributing lists the datasets that the currently authenticated user has access to because
+// they are a contributor.
 func (s *DatasetService) Contributing() (response []DatasetSummaryResponse, err error) {
 	return s.client.User.DatasetsContributing()
 }
 
+// Create a dataset and associated data.
 func (s *DatasetService) Create(owner string, body *DatasetCreateRequest) (response DatasetCreateResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s", owner)
 	headers := s.client.buildHeaders(POST, endpoint)
 	err = s.client.request(headers, body, &response)
 	return
 }
 
+// CreateOrReplace attempts to create a dataset with the given id, and will reset the dataset if it
+// already exists, redefining all of its attributes.
 func (s *DatasetService) CreateOrReplace(owner, id string, body *DatasetReplaceRequest) (
 	response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s", owner, id)
@@ -59,58 +72,93 @@ func (s *DatasetService) CreateOrReplace(owner, id string, body *DatasetReplaceR
 	return
 }
 
+// Delete a dataset and associated data.
 func (s *DatasetService) Delete(owner, datasetid string) (response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s", owner, datasetid)
 	headers := s.client.buildHeaders(DELETE, endpoint)
 	err = s.client.request(headers, nil, &response)
 	return
 }
 
+// DeleteDOI deletes a DOI (Digital Object Identifier) associated with a version of a dataset.
 func (s *DatasetService) DeleteDOI(owner, datasetid, doi string) (response SuccessResponse, err error) {
 	return s.client.DOI.Delete(owner, datasetid, doi)
 }
 
+// DeleteDOIAssociatedWithVersion deletes a DOI (Digital Object Identifier) associated with a version
+// of a dataset.
 func (s *DatasetService) DeleteDOIAssociatedWithVersion(owner, datasetid, versionid, doi string) (
 	response SuccessResponse, err error) {
 	return s.client.DOI.DeleteAssociatedWithVersion(owner, datasetid, versionid, doi)
 }
 
+// DownloadFile downloads a file within the dataset as originally uploaded.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *DatasetService) DownloadFile(owner, datasetid, filename string) (response io.Reader, err error) {
 	return s.client.File.Download(owner, datasetid, filename)
 }
 
+// DownloadAndSaveFile downloads a file within the dataset as originally uploaded, and saves the results
+// to a file.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *DatasetService) DownloadAndSaveFile(owner, datasetid, filename, path string) (
 	response SuccessResponse, err error) {
 	return s.client.File.DownloadAndSave(owner, datasetid, filename, path)
 }
 
+// Download downloads a .zip file containing all files within a dataset as originally uploaded.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *DatasetService) Download(owner, datasetid, filename string) (response io.Reader, err error) {
 	return s.client.File.DownloadDataset(owner, datasetid)
 }
 
+// DownloadAndSave downloads a .zip file containing all files within a dataset as originally
+// uploaded, and saves the results to a file.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *DatasetService) DownloadAndSave(owner, datasetid, path string) (response SuccessResponse, err error) {
 	return s.client.File.DownloadAndSaveDataset(owner, datasetid, path)
 }
 
+// Liked lists the datasets that the currently authenticated user has liked (bookmarked).
 func (s *DatasetService) Liked() (response []DatasetSummaryResponse, err error) {
 	return s.client.User.DatasetsLiked()
 }
 
+// ListQueries lists the saved queries associated with a dataset.
+//
+// Query definitions will be returned, not the query results. To retrieve the query results,
+// use `Query.ExecuteSavedQuery`.
 func (s *DatasetService) ListQueries(owner, datasetid string) (response []QuerySummaryResponse, err error) {
 	return s.client.Query.ListQueriesAssociatedWithDataset(owner, datasetid)
 }
 
+// Owned lists the datasets that the currently authenticated user has access to because they are
+// the owner.
 func (s *DatasetService) Owned() (response []DatasetSummaryResponse, err error) {
 	return s.client.User.DatasetsOwned()
 }
 
+// Retrieve fetches a dataset.
+//
+// The definition will be returned, not the associated data. Use `Query.ExecuteSQL()`
+// or `Query.ExecuteSPARQL()` to query the data. You can also download the original
+// files with `Dataset.Download` or `Dataset.DownloadFile`.
 func (s *DatasetService) Retrieve(owner, datasetid string) (response DatasetSummaryResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s", owner, datasetid)
 	headers := s.client.buildHeaders(GET, endpoint)
 	err = s.client.request(headers, nil, &response)
 	return
 }
 
+// Retrieve fetches a version of a dataset.
+//
+// The definition will be returned, not the associated data. Use `Query.ExecuteSQL()`
+// or `Query.ExecuteSPARQL()` to query the data. You can also download the original
+// files with `Dataset.Download` or `Dataset.DownloadFile`.
 func (s *DatasetService) RetrieveVersion(owner, datasetid, versionid string) (
 	response DatasetSummaryResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/v/%s", owner, datasetid, versionid)
@@ -119,17 +167,21 @@ func (s *DatasetService) RetrieveVersion(owner, datasetid, versionid string) (
 	return
 }
 
+// Sync files within a dataset. This method will process the latest data available for files added
+// from URLs or via streams.
 func (s *DatasetService) Sync(owner, datasetid string) (response SuccessResponse, err error) {
 	return s.client.File.Sync(owner, datasetid)
 }
 
+// Update a dataset.
 func (s *DatasetService) Update(owner, id string, body *DatasetUpdateRequest) (response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s", owner, id)
 	headers := s.client.buildHeaders(PATCH, endpoint)
 	err = s.client.request(headers, body, &response)
 	return
 }
 
+// UploadFile uploads one file at a time to a dataset.
 func (s *DatasetService) UploadFile(owner, id, filename, path string, expandArchive bool) (
 	response SuccessResponse, err error) {
 	return s.client.File.Upload(owner, id, filename, path, expandArchive)

dwapi/datasets_test.go

@@ -19,6 +19,7 @@ package dwapi
 
 import (
 	"fmt"
+	"log"
 	"net/http"
 	"testing"
 
@@ -53,6 +54,23 @@ func TestDatasetService_Create(t *testing.T) {
 	}
 }
 
+func ExampleDatasetService_Create() {
+	owner := "dataset-owner"
+	request := DatasetCreateRequest{
+		Title:       "My Awesome Dataset",
+		Description: "A short description",
+		Summary:     "A long description",
+		Tags:        []string{"first", "puppies and kittens"},
+		License:     "PDDL",
+		Visibility:  "PRIVATE",
+	}
+	response, err := dw.Dataset.Create(owner, &request)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println("Dataset URI:", response.URI)
+}
+
 func TestDatasetService_CreateOrReplace(t *testing.T) {
 	setup()
 	defer teardown()

dwapi/dois.go

@@ -25,13 +25,15 @@ type DoiService struct {
 	client *Client
 }
 
+// Associate a DOI (Digital Object Identifier) with a dataset.
 func (s *DoiService) Associate(owner, datasetid, doi string) (response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/dois/%s", owner, datasetid, doi)
 	headers := s.client.buildHeaders(PUT, endpoint)
 	err = s.client.request(headers, nil, &response)
 	return
 }
 
+// AssociateWithVersion associates a DOI (Digital Object Identifier) with a version of dataset.
 func (s *DoiService) AssociateWithVersion(owner, datasetid, versionid, doi string) (
 	response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/v/%s/dois/%s", owner, datasetid, versionid, doi)
@@ -40,13 +42,15 @@ func (s *DoiService) AssociateWithVersion(owner, datasetid, versionid, doi strin
 	return
 }
 
+// Delete a DOI (Digital Object Identifier) associated with a dataset.
 func (s *DoiService) Delete(owner, datasetid, doi string) (response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/dois/%s", owner, datasetid, doi)
 	headers := s.client.buildHeaders(DELETE, endpoint)
 	err = s.client.request(headers, nil, &response)
 	return
 }
 
+// DeleteAssociatedWithVersion deletes a DOI (Digital Object Identifier) associated with a dataset.
 func (s *DoiService) DeleteAssociatedWithVersion(owner, datasetid, versionid, doi string) (
 	response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/v/%s/dois/%s", owner, datasetid, versionid, doi)

dwapi/files.go

@@ -27,6 +27,12 @@ type FileService struct {
 	client *Client
 }
 
+// AddFilesFromURLs adds files from URLs to a dataset. This method allows files published on the web
+// to be added to a data.world dataset via their URL. This method can also be used to retrieve data
+// via web APIs, with advanced options for HTTP method, request payload and authentication.
+//
+// The source URL will be stored so you can easily update your file anytime it changes via the
+// `Sync now` button on the dataset page or by calling `File.Sync()`.
 func (s *FileService) AddFilesFromURLs(owner, id string, body *[]FileCreateRequest) (
 	response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/files", owner, id)
@@ -35,19 +41,27 @@ func (s *FileService) AddFilesFromURLs(owner, id string, body *[]FileCreateReque
 	return
 }
 
+// Delete a single file from a dataset.
 func (s *FileService) Delete(owner, id, filename string) (response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/files/%s", owner, id, filename)
 	headers := s.client.buildHeaders(DELETE, endpoint)
 	err = s.client.request(headers, nil, &response)
 	return
 }
 
+// Download a file within the dataset as originally uploaded.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *FileService) Download(owner, id, filename string) (response io.ReadCloser, err error) {
 	endpoint := fmt.Sprintf("/file_download/%s/%s/%s", owner, id, filename)
 	headers := s.client.buildHeaders(GET, endpoint)
 	return s.client.rawRequest(headers, nil)
 }
 
+// DownloadAndSave downloads a file within the dataset as originally uploaded, and saves the results
+// to a file.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *FileService) DownloadAndSave(owner, id, filename, path string) (response SuccessResponse, err error) {
 	r, err := s.Download(owner, id, filename)
 	if err != nil {
@@ -63,12 +77,19 @@ func (s *FileService) DownloadAndSave(owner, id, filename, path string) (respons
 	}, nil
 }
 
+// DownloadDataset downloads a .zip file containing all files within a dataset as originally uploaded.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *FileService) DownloadDataset(owner, id string) (response io.ReadCloser, err error) {
 	endpoint := fmt.Sprintf("/download/%s/%s", owner, id)
 	headers := s.client.buildHeaders(GET, endpoint)
 	return s.client.rawRequest(headers, nil)
 }
 
+// DownloadAndSaveDataset downloads a .zip file containing all files within a dataset as originally
+// uploaded, and saves the results to a file.
+//
+// Prefer `Query.ExecuteSQL()` or `Query.ExecuteSPARQL()` for retrieving clean and structured data.
 func (s *FileService) DownloadAndSaveDataset(owner, id, path string) (response SuccessResponse, err error) {
 	r, err := s.DownloadDataset(owner, id)
 	if err != nil {
@@ -84,13 +105,33 @@ func (s *FileService) DownloadAndSaveDataset(owner, id, path string) (response S
 	}, nil
 }
 
+// Sync files within a dataset. This method will process the latest data available for files added
+// from URLs or via streams.
 func (s *FileService) Sync(owner, id string) (response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/datasets/%s/%s/sync", owner, id)
 	headers := s.client.buildHeaders(GET, endpoint)
 	err = s.client.request(headers, nil, &response)
 	return
 }
 
+// Upload one file at a time to a dataset.
+func (s *FileService) Upload(owner, id, filename, path string, expandArchive bool) (
+	response SuccessResponse, err error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return
+	}
+
+	response, err = s.UploadStream(owner, id, filename, f, expandArchive)
+	if err != nil {
+		return
+	}
+
+	err = f.Close()
+	return
+}
+
+// UploadStream uploads the contents of an io.Reader to a file in a dataset.
 func (s *FileService) UploadStream(owner, id, filename string, body io.Reader, expandArchive bool) (
 	response SuccessResponse, err error) {
 	endpoint := fmt.Sprintf("/uploads/%s/%s/files/%s", owner, id, filename)
@@ -111,19 +152,3 @@ func (s *FileService) UploadStream(owner, id, filename string, body io.Reader, e
 	r.Close()
 	return
 }
-
-func (s *FileService) Upload(owner, id, filename, path string, expandArchive bool) (
-	response SuccessResponse, err error) {
-	f, err := os.Open(path)
-	if err != nil {
-		return
-	}
-
-	response, err = s.UploadStream(owner, id, filename, f, expandArchive)
-	if err != nil {
-		return
-	}
-
-	err = f.Close()
-	return
-}