docs: reference upstream docs in docstrings

hcloud/storage_box.go

@@ -11,6 +11,8 @@ import (
 )
 
 // StorageBox represents a Storage Box in Hetzner.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes
 type StorageBox struct {
 	ID             int64
 	Username       string
@@ -85,6 +87,8 @@ type StorageBoxClient struct {
 }
 
 // GetByID retrieves a [StorageBox] by its ID. If the [StorageBox] does not exist, nil is returned.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-get-a-storage-box
 func (c *StorageBoxClient) GetByID(ctx context.Context, id int64) (*StorageBox, *Response, error) {
 	const opPath = "/storage_boxes/%d"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -103,14 +107,19 @@ func (c *StorageBoxClient) GetByID(ctx context.Context, id int64) (*StorageBox,
 }
 
 // GetByName retrieves a [StorageBox] by its name. If the [StorageBox] does not exist, nil is returned.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-list-storage-boxes
 func (c *StorageBoxClient) GetByName(ctx context.Context, name string) (*StorageBox, *Response, error) {
 	return firstByName(name, func() ([]*StorageBox, *Response, error) {
 		return c.List(ctx, StorageBoxListOpts{Name: name})
 	})
 }
 
-// Get retrieves a [StorageBox] by its ID if the input can be parsed as an integer, otherwise it
-// retrieves a [StorageBox] by its name. If the [StorageBox] does not exist, nil is returned.
+// Get retrieves a [StorageBox] either by its ID or by its name, depending on whether
+// the input can be parsed as an integer. If no matching [StorageBox] is found, it returns nil.
+//
+// When fetching by ID, see https://docs.hetzner.cloud/reference/hetzner#storage-boxes-get-a-storage-box
+// When fetching by name, see https://docs.hetzner.cloud/reference/hetzner#storage-boxes-list-storage-boxes
 func (c *StorageBoxClient) Get(ctx context.Context, idOrName string) (*StorageBox, *Response, error) {
 	return getByIDOrName(ctx, c.GetByID, c.GetByName, idOrName)
 }
@@ -137,6 +146,8 @@ func (l StorageBoxListOpts) values() url.Values {
 //
 // Please note that filters specified in opts are not taken into account
 // when their value corresponds to their zero value or when they are empty.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-list-storage-boxes
 func (c *StorageBoxClient) List(ctx context.Context, opts StorageBoxListOpts) ([]*StorageBox, *Response, error) {
 	const opPath = "/storage_boxes?%s"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -152,11 +163,15 @@ func (c *StorageBoxClient) List(ctx context.Context, opts StorageBoxListOpts) ([
 }
 
 // All returns all [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-list-storage-boxes
 func (c *StorageBoxClient) All(ctx context.Context) ([]*StorageBox, error) {
 	return c.AllWithOpts(ctx, StorageBoxListOpts{ListOpts: ListOpts{PerPage: 50}})
 }
 
 // AllWithOpts returns all [StorageBox] with the given options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-list-storage-boxes
 func (c *StorageBoxClient) AllWithOpts(ctx context.Context, opts StorageBoxListOpts) ([]*StorageBox, error) {
 	return iterPages(func(page int) ([]*StorageBox, *Response, error) {
 		opts.Page = page
@@ -206,6 +221,8 @@ type StorageBoxCreateResult struct {
 // To provide SSH keys, populate the PublicKey field for each [SSHKey]
 // in the SSHKeys slice of [StorageBoxCreateOpts]. Only the PublicKey field
 // is sent to the API. They are not addressable by ID or name.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-create-a-storage-box
 func (c *StorageBoxClient) Create(ctx context.Context, opts StorageBoxCreateOpts) (StorageBoxCreateResult, *Response, error) {
 	const opPath = "/storage_boxes"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -236,6 +253,8 @@ type StorageBoxUpdateOpts struct {
 }
 
 // Update updates a [StorageBox] with the given options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-update-a-storage-box
 func (c *StorageBoxClient) Update(ctx context.Context, storageBox *StorageBox, opts StorageBoxUpdateOpts) (*StorageBox, *Response, error) {
 	const opPath = "/storage_boxes/%d"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -257,6 +276,8 @@ type StorageBoxDeleteResult struct {
 }
 
 // Delete deletes a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-delete-a-storage-box
 func (c *StorageBoxClient) Delete(ctx context.Context, storageBox *StorageBox) (StorageBoxDeleteResult, *Response, error) {
 	const opPath = "/storage_boxes/%d"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -292,6 +313,8 @@ func (o StorageBoxFoldersOpts) values() url.Values {
 }
 
 // Folders lists folders in a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-boxes-list-folders-of-a-storage-box
 func (c *StorageBoxClient) Folders(ctx context.Context, storageBox *StorageBox, opts StorageBoxFoldersOpts) (StorageBoxFoldersResult, *Response, error) {
 	const opPath = "/storage_boxes/%d/folders?%s"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -316,6 +339,8 @@ type StorageBoxChangeProtectionOpts struct {
 }
 
 // ChangeProtection changes the protection level of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-change-protection
 func (c *StorageBoxClient) ChangeProtection(ctx context.Context, storageBox *StorageBox, opts StorageBoxChangeProtectionOpts) (*Action, *Response, error) {
 	const opPath = "/storage_boxes/%d/actions/change_protection"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -337,6 +362,8 @@ type StorageBoxChangeTypeOpts struct {
 }
 
 // ChangeType changes the type of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-change-type
 func (c *StorageBoxClient) ChangeType(ctx context.Context, storageBox *StorageBox, opts StorageBoxChangeTypeOpts) (*Action, *Response, error) {
 	const opPath = "/storage_boxes/%d/actions/change_type"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -358,6 +385,8 @@ type StorageBoxResetPasswordOpts struct {
 }
 
 // ResetPassword resets the password of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-reset-password
 func (c *StorageBoxClient) ResetPassword(ctx context.Context, storageBox *StorageBox, opts StorageBoxResetPasswordOpts) (*Action, *Response, error) {
 	const opPath = "/storage_boxes/%d/actions/reset_password"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -383,6 +412,8 @@ type StorageBoxUpdateAccessSettingsOpts struct {
 }
 
 // UpdateAccessSettings updates the [StorageBoxAccessSettings] of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-update-access-settings
 func (c *StorageBoxClient) UpdateAccessSettings(ctx context.Context, storageBox *StorageBox, opts StorageBoxUpdateAccessSettingsOpts) (*Action, *Response, error) {
 	const opPath = "/storage_boxes/%d/actions/update_access_settings"
 	ctx = ctxutil.SetOpPath(ctx, opPath)
@@ -404,6 +435,8 @@ type StorageBoxRollbackSnapshotOpts struct {
 }
 
 // RollbackSnapshot rolls back a [StorageBox] to a [StorageBoxSnapshot].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-rollback-snapshot
 func (c *StorageBoxClient) RollbackSnapshot(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -440,6 +473,8 @@ type StorageBoxEnableSnapshotPlanOpts struct {
 }
 
 // EnableSnapshotPlan enables a [StorageBoxSnapshotPlan] for a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-enable-snapshot-plan
 func (c *StorageBoxClient) EnableSnapshotPlan(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -460,6 +495,8 @@ func (c *StorageBoxClient) EnableSnapshotPlan(
 }
 
 // DisableSnapshotPlan disables the [StorageBoxSnapshotPlan] for a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-actions-disable-snapshot-plan
 func (c *StorageBoxClient) DisableSnapshotPlan(
 	ctx context.Context,
 	storageBox *StorageBox,

hcloud/storage_box_snapshot.go

@@ -11,6 +11,8 @@ import (
 )
 
 // StorageBoxSnapshot represents a snapshot of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots
 type StorageBoxSnapshot struct {
 	ID          int64
 	Name        string
@@ -29,6 +31,8 @@ type StorageBoxSnapshotStats struct {
 }
 
 // GetSnapshotByID gets a [StorageBoxSnapshot] by its ID.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-get-a-snapshot
 func (c *StorageBoxClient) GetSnapshotByID(ctx context.Context, storageBox *StorageBox, id int64) (*StorageBoxSnapshot, *Response, error) {
 	const optPath = "/storage_boxes/%d/snapshots/%d"
 	ctx = ctxutil.SetOpPath(ctx, optPath)
@@ -47,6 +51,8 @@ func (c *StorageBoxClient) GetSnapshotByID(ctx context.Context, storageBox *Stor
 }
 
 // GetSnapshotByName gets a [StorageBoxSnapshot] by its name.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-list-snapshots
 func (c *StorageBoxClient) GetSnapshotByName(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -57,7 +63,11 @@ func (c *StorageBoxClient) GetSnapshotByName(
 	})
 }
 
-// GetSnapshot gets a [StorageBoxSnapshot] by its ID or name.
+// GetSnapshot retrieves a [StorageBoxSnapshot] either by its ID or by its name, depending on whether
+// the input can be parsed as an integer. If no matching [StorageBoxSnapshot] is found, it returns nil.
+//
+// When fetching by ID, see https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-get-a-snapshot
+// When fetching by name, see https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-list-snapshots
 func (c *StorageBoxClient) GetSnapshot(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -103,6 +113,8 @@ func (o StorageBoxSnapshotListOpts) values() url.Values {
 // ListSnapshots lists all [StorageBoxSnapshot] of a [StorageBox] with the given options.
 //
 // Pagination is not supported, so this will return all [StorageBoxSnapshot] at once.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-list-snapshots
 func (c *StorageBoxClient) ListSnapshots(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -122,6 +134,8 @@ func (c *StorageBoxClient) ListSnapshots(
 }
 
 // AllSnapshotsWithOpts lists all [StorageBoxSnapshot] of a [StorageBox] with the given options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-list-snapshots
 func (c *StorageBoxClient) AllSnapshotsWithOpts(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -132,6 +146,8 @@ func (c *StorageBoxClient) AllSnapshotsWithOpts(
 }
 
 // AllSnapshots lists all [StorageBoxSnapshot] of a [StorageBox] without any options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-list-snapshots
 func (c *StorageBoxClient) AllSnapshots(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -154,6 +170,8 @@ type StorageBoxSnapshotCreateResult struct {
 }
 
 // CreateSnapshot creates a new [StorageBoxSnapshot] for the given [StorageBox] with the provided options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-create-a-snapshot
 func (c *StorageBoxClient) CreateSnapshot(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -185,6 +203,8 @@ type StorageBoxSnapshotUpdateOpts struct {
 }
 
 // UpdateSnapshot updates the given [StorageBoxSnapshot] of a [StorageBox] with the provided options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-update-a-snapshot
 func (c *StorageBoxClient) UpdateSnapshot(
 	ctx context.Context,
 	snapshot *StorageBoxSnapshot,
@@ -210,6 +230,8 @@ type StorageBoxSnapshotDeleteResult struct {
 }
 
 // DeleteSnapshot deletes the given [StorageBoxSnapshot] of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-snapshots-delete-a-snapshot
 func (c *StorageBoxClient) DeleteSnapshot(
 	ctx context.Context,
 	snapshot *StorageBoxSnapshot,

hcloud/storage_box_subaccount.go

@@ -11,6 +11,8 @@ import (
 )
 
 // StorageBoxSubaccount represents a subaccount of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts
 type StorageBoxSubaccount struct {
 	ID             int64
 	Username       string
@@ -32,7 +34,11 @@ type StorageBoxSubaccountAccessSettings struct {
 	WebDAVEnabled       bool
 }
 
-// GetSubaccount retrieves a [StorageBoxSubaccount] by its ID or username.
+// GetSubaccount retrieves a [StorageBoxSubaccount] either by its ID or by its username, depending on whether
+// the input can be parsed as an integer. If no matching [StorageBoxSubaccount] is found, it returns nil.
+//
+// When fetching by ID, see https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-get-a-subaccount
+// When fetching by name, see https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-list-subaccounts
 func (c *StorageBoxClient) GetSubaccount(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -51,6 +57,8 @@ func (c *StorageBoxClient) GetSubaccount(
 }
 
 // GetSubaccountByID retrieves a [StorageBoxSubaccount] by its ID.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-get-a-subaccount
 func (c *StorageBoxClient) GetSubaccountByID(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -73,6 +81,8 @@ func (c *StorageBoxClient) GetSubaccountByID(
 }
 
 // GetSubaccountByUsername retrieves a [StorageBoxSubaccount] by its username.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-list-subaccounts
 func (c *StorageBoxClient) GetSubaccountByUsername(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -107,6 +117,8 @@ func (o StorageBoxSubaccountListOpts) values() url.Values {
 }
 
 // ListSubaccounts lists all [StorageBoxSubaccount] of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-list-subaccounts
 func (c *StorageBoxClient) ListSubaccounts(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -126,6 +138,8 @@ func (c *StorageBoxClient) ListSubaccounts(
 }
 
 // AllSubaccountsWithOpts retrieves all [StorageBoxSubaccount] of a [StorageBox] with the given options.
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-list-subaccounts
 func (c *StorageBoxClient) AllSubaccountsWithOpts(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -136,6 +150,8 @@ func (c *StorageBoxClient) AllSubaccountsWithOpts(
 }
 
 // AllSubaccounts retrieves all [StorageBoxSubaccount] of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-list-subaccounts
 func (c *StorageBoxClient) AllSubaccounts(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -170,6 +186,8 @@ type StorageBoxSubaccountCreateResult struct {
 }
 
 // CreateSubaccount creates a new [StorageBoxSubaccount] for a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-create-a-subaccount
 func (c *StorageBoxClient) CreateSubaccount(
 	ctx context.Context,
 	storageBox *StorageBox,
@@ -201,6 +219,8 @@ type StorageBoxSubaccountUpdateOpts struct {
 }
 
 // UpdateSubaccount updates a [StorageBoxSubaccount] of a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-update-a-subaccount
 func (c *StorageBoxClient) UpdateSubaccount(
 	ctx context.Context,
 	subaccount *StorageBoxSubaccount,
@@ -226,6 +246,8 @@ type StorageBoxSubaccountDeleteResult struct {
 }
 
 // DeleteSubaccount deletes a [StorageBoxSubaccount] from a [StorageBox].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccounts-delete-a-subaccount
 func (c *StorageBoxClient) DeleteSubaccount(
 	ctx context.Context,
 	subaccount *StorageBoxSubaccount,
@@ -252,6 +274,8 @@ type StorageBoxSubaccountResetPasswordOpts struct {
 }
 
 // ResetSubaccountPassword resets the password of a [StorageBoxSubaccount].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccount-actions-reset-password
 func (c *StorageBoxClient) ResetSubaccountPassword(
 	ctx context.Context,
 	subaccount *StorageBoxSubaccount,
@@ -281,6 +305,8 @@ type StorageBoxSubaccountUpdateAccessSettingsOpts struct {
 }
 
 // UpdateSubaccountAccessSettings updates the [StorageBoxSubaccountAccessSettings] of a [StorageBoxSubaccount].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccount-actions-update-access-settings
 func (c *StorageBoxClient) UpdateSubaccountAccessSettings(
 	ctx context.Context,
 	subaccount *StorageBoxSubaccount,
@@ -306,6 +332,8 @@ type StorageBoxSubaccountChangeHomeDirectoryOpts struct {
 }
 
 // UpdateSubaccountAccessSettings changes the home directory of a [StorageBoxSubaccount].
+//
+// See https://docs.hetzner.cloud/reference/hetzner#storage-box-subaccount-actions-change-home-directory
 func (c *StorageBoxClient) ChangeSubaccountHomeDirectory(
 	ctx context.Context,
 	subaccount *StorageBoxSubaccount,