From 751741d87eba5d90007bea6330870da1619a0bc8 Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Mon, 8 Jan 2024 14:35:19 +0100
Subject: [PATCH] webdav: add/improve doc comments

---
 client.go   | 16 ++++++++++++++++
 fs_local.go |  1 +
 server.go   |  4 +++-
 webdav.go   |  1 +
 4 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/client.go b/client.go
index e9cf259..ae07251 100644
--- a/client.go
+++ b/client.go
@@ -40,6 +40,11 @@ type Client struct {
 	ic *internal.Client
 }
 
+// NewClient creates a new WebDAV client.
+//
+// If the HTTPClient is nil, http.DefaultClient is used.
+//
+// To use HTTP basic authentication, HTTPClientWithBasicAuth can be used.
 func NewClient(c HTTPClient, endpoint string) (*Client, error) {
 	ic, err := internal.NewClient(c, endpoint)
 	if err != nil {
@@ -48,6 +53,7 @@ func NewClient(c HTTPClient, endpoint string) (*Client, error) {
 	return &Client{ic}, nil
 }
 
+// FindCurrentUserPrincipal finds the current user's principal path.
 func (c *Client) FindCurrentUserPrincipal(ctx context.Context) (string, error) {
 	propfind := internal.NewPropNamePropFind(internal.CurrentUserPrincipalName)
 
@@ -122,6 +128,7 @@ func fileInfoFromResponse(resp *internal.Response) (*FileInfo, error) {
 	return fi, nil
 }
 
+// Stat fetches a FileInfo for a single file.
 func (c *Client) Stat(ctx context.Context, name string) (*FileInfo, error) {
 	resp, err := c.ic.PropFindFlat(ctx, name, fileInfoPropFind)
 	if err != nil {
@@ -130,6 +137,7 @@ func (c *Client) Stat(ctx context.Context, name string) (*FileInfo, error) {
 	return fileInfoFromResponse(resp)
 }
 
+// Open fetches a file's contents.
 func (c *Client) Open(ctx context.Context, name string) (io.ReadCloser, error) {
 	req, err := c.ic.NewRequest(http.MethodGet, name, nil)
 	if err != nil {
@@ -144,6 +152,7 @@ func (c *Client) Open(ctx context.Context, name string) (io.ReadCloser, error) {
 	return resp.Body, nil
 }
 
+// Readdir lists files in a directory.
 func (c *Client) Readdir(ctx context.Context, name string, recursive bool) ([]FileInfo, error) {
 	depth := internal.DepthOne
 	if recursive {
@@ -183,6 +192,7 @@ func (fw *fileWriter) Close() error {
 	return <-fw.done
 }
 
+// Create writes a file's contents.
 func (c *Client) Create(ctx context.Context, name string) (io.WriteCloser, error) {
 	pr, pw := io.Pipe()
 
@@ -206,6 +216,8 @@ func (c *Client) Create(ctx context.Context, name string) (io.WriteCloser, error
 	return &fileWriter{pw, done}, nil
 }
 
+// RemoveAll deletes a file. If the file is a directory, all of its descendants
+// are recursively deleted as well.
 func (c *Client) RemoveAll(ctx context.Context, name string) error {
 	req, err := c.ic.NewRequest(http.MethodDelete, name, nil)
 	if err != nil {
@@ -220,6 +232,7 @@ func (c *Client) RemoveAll(ctx context.Context, name string) error {
 	return nil
 }
 
+// Mkdir creates a new directory.
 func (c *Client) Mkdir(ctx context.Context, name string) error {
 	req, err := c.ic.NewRequest("MKCOL", name, nil)
 	if err != nil {
@@ -234,6 +247,8 @@ func (c *Client) Mkdir(ctx context.Context, name string) error {
 	return nil
 }
 
+// CopyAll copies a file. If the file is a directory, all of its descendants
+// are recursively copied as well.
 func (c *Client) CopyAll(ctx context.Context, name, dest string, overwrite bool) error {
 	req, err := c.ic.NewRequest("COPY", name, nil)
 	if err != nil {
@@ -251,6 +266,7 @@ func (c *Client) CopyAll(ctx context.Context, name, dest string, overwrite bool)
 	return nil
 }
 
+// MoveAll moves a file.
 func (c *Client) MoveAll(ctx context.Context, name, dest string, overwrite bool) error {
 	req, err := c.ic.NewRequest("MOVE", name, nil)
 	if err != nil {
diff --git a/fs_local.go b/fs_local.go
index 1e60956..1366f4b 100644
--- a/fs_local.go
+++ b/fs_local.go
@@ -14,6 +14,7 @@ import (
 	"github.com/emersion/go-webdav/internal"
 )
 
+// LocalFileSystem implements FileSystem for a local directory.
 type LocalFileSystem string
 
 var _ FileSystem = LocalFileSystem("")
diff --git a/server.go b/server.go
index fc38a9f..617cb69 100644
--- a/server.go
+++ b/server.go
@@ -248,7 +248,7 @@ func (b *backend) Move(r *http.Request, dest *internal.Href, overwrite bool) (cr
 
 // BackendSuppliedHomeSet represents either a CalDAV calendar-home-set or a
 // CardDAV addressbook-home-set. It should only be created via
-// `caldav.NewCalendarHomeSet()` or `carddav.NewAddressbookHomeSet()`. Only to
+// caldav.NewCalendarHomeSet or carddav.NewAddressbookHomeSet. Only to
 // be used server-side, for listing a user's home sets as determined by the
 // (external) backend.
 type BackendSuppliedHomeSet interface {
@@ -261,8 +261,10 @@ type UserPrincipalBackend interface {
 	CurrentUserPrincipal(ctx context.Context) (string, error)
 }
 
+// Capability indicates the features that a server supports.
 type Capability string
 
+// ServePrincipalOptions holds options for ServePrincipal.
 type ServePrincipalOptions struct {
 	CurrentUserPrincipalPath string
 	HomeSets                 []BackendSuppliedHomeSet
diff --git a/webdav.go b/webdav.go
index 4dd369c..7397f9f 100644
--- a/webdav.go
+++ b/webdav.go
@@ -7,6 +7,7 @@ import (
 	"time"
 )
 
+// FileInfo holds information about a WebDAV file.
 type FileInfo struct {
 	Path     string
 	Size     int64