From c0517de9be5a39afa716551b2b8a4f7a0f9065f7 Mon Sep 17 00:00:00 2001 From: Evgenii Baidakov Date: Thu, 13 Jul 2023 08:24:25 +0400 Subject: [PATCH] object: Update documentation closes #226 Signed-off-by: Evgenii Baidakov --- object/attribute.go | 26 +++++--- object/error.go | 4 ++ object/id/address.go | 2 +- object/id/id.go | 2 +- object/lock.go | 22 ++++--- object/object.go | 137 +++++++++++++++++++++++++++++++++---------- object/range.go | 20 +++++-- object/search.go | 44 ++++++++++---- object/splitid.go | 8 +-- object/splitinfo.go | 37 +++++++++++- object/tombstone.go | 44 +++++++++----- object/type.go | 19 +++--- 12 files changed, 267 insertions(+), 98 deletions(-) diff --git a/object/attribute.go b/object/attribute.go index 7c74cb96..b9976413 100644 --- a/object/attribute.go +++ b/object/attribute.go @@ -7,14 +7,14 @@ import ( // Attribute represents v2-compatible object attribute. type Attribute object.Attribute -// NewAttributeFromV2 wraps v2 Attribute message to Attribute. +// NewAttributeFromV2 wraps v2 [object.Attribute] message to [Attribute]. // -// Nil object.Attribute converts to nil. +// Nil [object.Attribute] converts to nil. func NewAttributeFromV2(aV2 *object.Attribute) *Attribute { return (*Attribute)(aV2) } -// NewAttribute creates and initializes blank Attribute. +// NewAttribute creates and initializes blank [Attribute]. // // Works similar as NewAttributeFromV2(new(Attribute)). // @@ -45,29 +45,37 @@ func (a *Attribute) SetValue(v string) { (*object.Attribute)(a).SetValue(v) } -// ToV2 converts Attribute to v2 Attribute message. +// ToV2 converts [Attribute] to v2 [object.Attribute] message. // -// Nil Attribute converts to nil. +// Nil [Attribute] converts to nil. func (a *Attribute) ToV2() *object.Attribute { return (*object.Attribute)(a) } -// Marshal marshals Attribute into a protobuf binary form. +// Marshal marshals [Attribute] into a protobuf binary form. +// +// See also [Attribute.Unmarshal]. func (a *Attribute) Marshal() ([]byte, error) { return (*object.Attribute)(a).StableMarshal(nil), nil } -// Unmarshal unmarshals protobuf binary representation of Attribute. +// Unmarshal unmarshals protobuf binary representation of [Attribute]. +// +// See also [Attribute.Marshal]. func (a *Attribute) Unmarshal(data []byte) error { return (*object.Attribute)(a).Unmarshal(data) } -// MarshalJSON encodes Attribute to protobuf JSON format. +// MarshalJSON encodes [Attribute] to protobuf JSON format. +// +// See also [Attribute.UnmarshalJSON]. func (a *Attribute) MarshalJSON() ([]byte, error) { return (*object.Attribute)(a).MarshalJSON() } -// UnmarshalJSON decodes Attribute from protobuf JSON format. +// UnmarshalJSON decodes [Attribute] from protobuf JSON format. +// +// See also [Attribute.MarshalJSON]. func (a *Attribute) UnmarshalJSON(data []byte) error { return (*object.Attribute)(a).UnmarshalJSON(data) } diff --git a/object/error.go b/object/error.go index 96048c28..593cb41b 100644 --- a/object/error.go +++ b/object/error.go @@ -1,19 +1,23 @@ package object +// SplitInfoError is a special error that means that the original object is a large one (split into a number of smaller objects). type SplitInfoError struct { si *SplitInfo } const splitInfoErrorMsg = "object not found, split info has been provided" +// Error implements the error interface. func (s *SplitInfoError) Error() string { return splitInfoErrorMsg } +// SplitInfo returns [SplitInfo] data. func (s *SplitInfoError) SplitInfo() *SplitInfo { return s.si } +// NewSplitInfoError is a constructor for [SplitInfoError]. func NewSplitInfoError(v *SplitInfo) *SplitInfoError { return &SplitInfoError{si: v} } diff --git a/object/id/address.go b/object/id/address.go index 3d34d1c8..1b07d0b6 100644 --- a/object/id/address.go +++ b/object/id/address.go @@ -161,7 +161,7 @@ func (x *Address) DecodeString(s string) error { return nil } -// String implements fmt.Stringer. +// String implements [fmt.Stringer]. // // String is designed to be human-readable, and its format MAY differ between // SDK versions. String MAY return same result as EncodeToString. String MUST NOT diff --git a/object/id/id.go b/object/id/id.go index ab923b8f..c3436b56 100644 --- a/object/id/id.go +++ b/object/id/id.go @@ -105,7 +105,7 @@ func (id *ID) DecodeString(s string) error { return id.Decode(data) } -// String implements fmt.Stringer. +// String implements [fmt.Stringer]. // // String is designed to be human-readable, and its format MAY differ between // SDK versions. String MAY return same result as EncodeToString. String MUST NOT diff --git a/object/lock.go b/object/lock.go index 6e5acbef..a3972899 100644 --- a/object/lock.go +++ b/object/lock.go @@ -9,10 +9,10 @@ import ( // Lock represents record with locked objects. It is compatible with // NeoFS API V2 protocol. // -// Lock instance can be written to the Object, see WriteLock/ReadLock. +// Lock instance can be written to the [Object], see WriteLock/ReadLock. type Lock v2object.Lock -// WriteLock writes Lock to the Object, and sets its type to TypeLock. +// WriteLock writes [Lock] to the [Object], and sets its type to [TypeLock]. // // See also ReadLock. func (o *Object) WriteLock(l Lock) { @@ -20,11 +20,11 @@ func (o *Object) WriteLock(l Lock) { o.SetPayload(l.Marshal()) } -// ReadLock reads Lock from the Object. The lock must not be nil. +// ReadLock reads [Lock] from the [Object]. The lock must not be nil. // Returns an error describing incorrect format. Makes sense only -// if object has TypeLock type. +// if object has [TypeLock] type. // -// See also WriteLock. +// See also [Object.WriteLock]. func (o *Object) ReadLock(l *Lock) error { return l.Unmarshal(o.Payload()) } @@ -36,7 +36,7 @@ func (x Lock) NumberOfMembers() int { // ReadMembers reads list of locked members. // -// Buffer length must not be less than NumberOfMembers. +// Buffer length must not be less than [Lock.NumberOfMembers]. func (x Lock) ReadMembers(buf []oid.ID) { var i int @@ -47,6 +47,8 @@ func (x Lock) ReadMembers(buf []oid.ID) { } // WriteMembers writes list of locked members. +// +// See also [Lock.ReadMembers]. func (x *Lock) WriteMembers(ids []oid.ID) { var members []refs.ObjectID @@ -61,12 +63,16 @@ func (x *Lock) WriteMembers(ids []oid.ID) { (*v2object.Lock)(x).SetMembers(members) } -// Marshal encodes the Lock into a NeoFS protocol binary format. +// Marshal encodes the [Lock] into a NeoFS protocol binary format. +// +// See also [Lock.Unmarshal]. func (x Lock) Marshal() []byte { return (*v2object.Lock)(&x).StableMarshal(nil) } -// Unmarshal decodes the Lock from its NeoFS protocol binary representation. +// Unmarshal decodes the [Lock] from its NeoFS protocol binary representation. +// +// See also [Lock.Marshal]. func (x *Lock) Unmarshal(data []byte) error { return (*v2object.Lock)(x).Unmarshal(data) } diff --git a/object/object.go b/object/object.go index 50778323..c956bad6 100644 --- a/object/object.go +++ b/object/object.go @@ -20,7 +20,7 @@ import ( // Type is compatible with NeoFS API V2 protocol. // // Instance can be created depending on scenario: -// - InitCreation (an object to be placed in container); +// - [Object.InitCreation] (an object to be placed in container); // - New (blank instance, usually needed for decoding); // - NewFromV2 (when working under NeoFS API V2 protocol). type Object object.Object @@ -41,25 +41,24 @@ func (o *Object) InitCreation(rf RequiredFields) { o.SetOwnerID(&rf.Owner) } -// NewFromV2 wraps v2 Object message to Object. +// NewFromV2 wraps v2 [object.Object] message to [Object]. func NewFromV2(oV2 *object.Object) *Object { return (*Object)(oV2) } -// New creates and initializes blank Object. +// New creates and initializes blank [Object]. // // Works similar as NewFromV2(new(Object)). func New() *Object { return NewFromV2(new(object.Object)) } -// ToV2 converts Object to v2 Object message. +// ToV2 converts [Object] to v2 [object.Object] message. func (o *Object) ToV2() *object.Object { return (*object.Object)(o) } -// MarshalHeaderJSON marshals object's header -// into JSON format. +// MarshalHeaderJSON marshals object's header into JSON format. func (o *Object) MarshalHeaderJSON() ([]byte, error) { return (*object.Object)(o).GetHeader().MarshalJSON() } @@ -89,6 +88,8 @@ func (o *Object) setSplitFields(setter func(*object.SplitHeader)) { } // ID returns object identifier. +// +// See also [Object.SetID]. func (o *Object) ID() (v oid.ID, isSet bool) { v2 := (*object.Object)(o) if id := v2.GetObjectID(); id != nil { @@ -100,6 +101,8 @@ func (o *Object) ID() (v oid.ID, isSet bool) { } // SetID sets object identifier. +// +// See also [Object.ID]. func (o *Object) SetID(v oid.ID) { var v2 refs.ObjectID v.WriteToV2(&v2) @@ -109,6 +112,8 @@ func (o *Object) SetID(v oid.ID) { } // Signature returns signature of the object identifier. +// +// See also [Object.SetSignature]. func (o *Object) Signature() *neofscrypto.Signature { sigv2 := (*object.Object)(o).GetSignature() if sigv2 == nil { @@ -122,6 +127,8 @@ func (o *Object) Signature() *neofscrypto.Signature { } // SetSignature sets signature of the object identifier. +// +// See also [Object.Signature]. func (o *Object) SetSignature(v *neofscrypto.Signature) { var sigv2 *refs.Signature @@ -135,16 +142,22 @@ func (o *Object) SetSignature(v *neofscrypto.Signature) { } // Payload returns payload bytes. +// +// See also [Object.SetPayload]. func (o *Object) Payload() []byte { return (*object.Object)(o).GetPayload() } // SetPayload sets payload bytes. +// +// See also [Object.Payload]. func (o *Object) SetPayload(v []byte) { (*object.Object)(o).SetPayload(v) } // Version returns version of the object. +// +// See also [Object.SetVersion]. func (o *Object) Version() *version.Version { var ver version.Version if verV2 := (*object.Object)(o).GetHeader().GetVersion(); verV2 != nil { @@ -154,6 +167,8 @@ func (o *Object) Version() *version.Version { } // SetVersion sets version of the object. +// +// See also [Object.Version]. func (o *Object) SetVersion(v *version.Version) { var verV2 refs.Version v.WriteToV2(&verV2) @@ -164,6 +179,8 @@ func (o *Object) SetVersion(v *version.Version) { } // PayloadSize returns payload length of the object. +// +// See also [Object.SetPayloadSize]. func (o *Object) PayloadSize() uint64 { return (*object.Object)(o). GetHeader(). @@ -171,6 +188,8 @@ func (o *Object) PayloadSize() uint64 { } // SetPayloadSize sets payload length of the object. +// +// See also [Object.PayloadSize]. func (o *Object) SetPayloadSize(v uint64) { o.setHeaderField(func(h *object.Header) { h.SetPayloadLength(v) @@ -178,6 +197,8 @@ func (o *Object) SetPayloadSize(v uint64) { } // ContainerID returns identifier of the related container. +// +// See also [Object.SetContainerID]. func (o *Object) ContainerID() (v cid.ID, isSet bool) { v2 := (*object.Object)(o) @@ -191,6 +212,8 @@ func (o *Object) ContainerID() (v cid.ID, isSet bool) { } // SetContainerID sets identifier of the related container. +// +// See also [Object.ContainerID]. func (o *Object) SetContainerID(v cid.ID) { var cidV2 refs.ContainerID v.WriteToV2(&cidV2) @@ -201,6 +224,8 @@ func (o *Object) SetContainerID(v cid.ID) { } // OwnerID returns identifier of the object owner. +// +// See also [Object.SetOwnerID]. func (o *Object) OwnerID() *user.ID { var id user.ID @@ -213,6 +238,8 @@ func (o *Object) OwnerID() *user.ID { } // SetOwnerID sets identifier of the object owner. +// +// See also [Object.OwnerID]. func (o *Object) SetOwnerID(v *user.ID) { o.setHeaderField(func(h *object.Header) { var m refs.OwnerID @@ -223,6 +250,8 @@ func (o *Object) SetOwnerID(v *user.ID) { } // CreationEpoch returns epoch number in which object was created. +// +// See also [Object.SetCreationEpoch]. func (o *Object) CreationEpoch() uint64 { return (*object.Object)(o). GetHeader(). @@ -230,6 +259,8 @@ func (o *Object) CreationEpoch() uint64 { } // SetCreationEpoch sets epoch number in which object was created. +// +// See also [Object.CreationEpoch]. func (o *Object) SetCreationEpoch(v uint64) { o.setHeaderField(func(h *object.Header) { h.SetCreationEpoch(v) @@ -239,9 +270,9 @@ func (o *Object) SetCreationEpoch(v uint64) { // PayloadChecksum returns checksum of the object payload and // bool that indicates checksum presence in the object. // -// Zero Object does not have payload checksum. +// Zero [Object] does not have payload checksum. // -// See also SetPayloadChecksum. +// See also [Object.SetPayloadChecksum]. func (o *Object) PayloadChecksum() (checksum.Checksum, bool) { var v checksum.Checksum v2 := (*object.Object)(o) @@ -256,7 +287,7 @@ func (o *Object) PayloadChecksum() (checksum.Checksum, bool) { // SetPayloadChecksum sets checksum of the object payload. // -// See also PayloadChecksum. +// See also [Object.PayloadChecksum]. func (o *Object) SetPayloadChecksum(v checksum.Checksum) { var v2 refs.Checksum v.WriteToV2(&v2) @@ -269,9 +300,9 @@ func (o *Object) SetPayloadChecksum(v checksum.Checksum) { // PayloadHomomorphicHash returns homomorphic hash of the object // payload and bool that indicates checksum presence in the object. // -// Zero Object does not have payload homomorphic checksum. +// Zero [Object] does not have payload homomorphic checksum. // -// See also SetPayloadHomomorphicHash. +// See also [Object.SetPayloadHomomorphicHash]. func (o *Object) PayloadHomomorphicHash() (checksum.Checksum, bool) { var v checksum.Checksum v2 := (*object.Object)(o) @@ -286,7 +317,7 @@ func (o *Object) PayloadHomomorphicHash() (checksum.Checksum, bool) { // SetPayloadHomomorphicHash sets homomorphic hash of the object payload. // -// See also PayloadHomomorphicHash. +// See also [Object.PayloadHomomorphicHash]. func (o *Object) SetPayloadHomomorphicHash(v checksum.Checksum) { var v2 refs.Checksum v.WriteToV2(&v2) @@ -325,6 +356,8 @@ func (o *Object) SetAttributes(v ...Attribute) { } // PreviousID returns identifier of the previous sibling object. +// +// See also [Object.SetPreviousID]. func (o *Object) PreviousID() (v oid.ID, isSet bool) { v2 := (*object.Object)(o) @@ -338,6 +371,8 @@ func (o *Object) PreviousID() (v oid.ID, isSet bool) { } // ResetPreviousID resets identifier of the previous sibling object. +// +// See also [Object.SetPreviousID], [Object.PreviousID]. func (o *Object) ResetPreviousID() { o.setSplitFields(func(split *object.SplitHeader) { split.SetPrevious(nil) @@ -345,6 +380,8 @@ func (o *Object) ResetPreviousID() { } // SetPreviousID sets identifier of the previous sibling object. +// +// See also [Object.PreviousID]. func (o *Object) SetPreviousID(v oid.ID) { var v2 refs.ObjectID v.WriteToV2(&v2) @@ -355,6 +392,8 @@ func (o *Object) SetPreviousID(v oid.ID) { } // Children return list of the identifiers of the child objects. +// +// See also [Object.SetChildren]. func (o *Object) Children() []oid.ID { v2 := (*object.Object)(o) ids := v2.GetHeader().GetSplit().GetChildren() @@ -373,6 +412,8 @@ func (o *Object) Children() []oid.ID { } // SetChildren sets list of the identifiers of the child objects. +// +// See also [Object.Children]. func (o *Object) SetChildren(v ...oid.ID) { var ( v2 refs.ObjectID @@ -397,34 +438,38 @@ type NotificationInfo struct { ni object.NotificationInfo } -// Epoch returns object notification tick -// epoch. +// Epoch returns object notification tick epoch. +// +// See also [NotificationInfo.SetEpoch]. func (n NotificationInfo) Epoch() uint64 { return n.ni.Epoch() } -// SetEpoch sets object notification tick -// epoch. +// SetEpoch sets object notification tick epoch. +// +// See also [NotificationInfo.Epoch]. func (n *NotificationInfo) SetEpoch(epoch uint64) { n.ni.SetEpoch(epoch) } -// Topic return optional object notification -// topic. +// Topic return optional object notification topic. +// +// See also [NotificationInfo.SetTopic]. func (n NotificationInfo) Topic() string { return n.ni.Topic() } -// SetTopic sets optional object notification -// topic. +// SetTopic sets optional object notification topic. +// +// See also [NotificationInfo.Topic]. func (n *NotificationInfo) SetTopic(topic string) { n.ni.SetTopic(topic) } -// NotificationInfo returns notification info -// read from the object structure. -// Returns any error that appeared during notification -// information parsing. +// NotificationInfo returns notification info read from the object structure. +// Returns any error that appeared during notification information parsing. +// +// See also [Object.SetNotification]. func (o *Object) NotificationInfo() (*NotificationInfo, error) { ni, err := object.GetNotificationInfo((*object.Object)(o)) if err != nil { @@ -436,13 +481,16 @@ func (o *Object) NotificationInfo() (*NotificationInfo, error) { }, nil } -// SetNotification writes NotificationInfo to the object structure. +// SetNotification writes [NotificationInfo] to the object structure. +// +// See also [Object.NotificationInfo]. func (o *Object) SetNotification(ni NotificationInfo) { object.WriteNotificationInfo((*object.Object)(o), ni.ni) } -// SplitID return split identity of split object. If object is not split -// returns nil. +// SplitID return split identity of split object. If object is not split returns nil. +// +// See also [Object.SetSplitID]. func (o *Object) SplitID() *SplitID { return NewSplitIDFromV2( (*object.Object)(o). @@ -453,6 +501,8 @@ func (o *Object) SplitID() *SplitID { } // SetSplitID sets split identifier for the split object. +// +// See also [Object.SplitID]. func (o *Object) SetSplitID(id *SplitID) { o.setSplitFields(func(split *object.SplitHeader) { split.SetSplitID(id.ToV2()) @@ -460,6 +510,8 @@ func (o *Object) SetSplitID(id *SplitID) { } // ParentID returns identifier of the parent object. +// +// See also [Object.SetParentID]. func (o *Object) ParentID() (v oid.ID, isSet bool) { v2 := (*object.Object)(o) @@ -473,6 +525,8 @@ func (o *Object) ParentID() (v oid.ID, isSet bool) { } // SetParentID sets identifier of the parent object. +// +// See also [Object.ParentID]. func (o *Object) SetParentID(v oid.ID) { var v2 refs.ObjectID v.WriteToV2(&v2) @@ -483,6 +537,8 @@ func (o *Object) SetParentID(v oid.ID) { } // Parent returns parent object w/o payload. +// +// See also [Object.SetParent]. func (o *Object) Parent() *Object { h := (*object.Object)(o). GetHeader(). @@ -504,6 +560,8 @@ func (o *Object) Parent() *Object { } // SetParent sets parent object w/o payload. +// +// See also [Object.Parent]. func (o *Object) SetParent(v *Object) { o.setSplitFields(func(split *object.SplitHeader) { split.SetParent((*object.Object)(v).GetObjectID()) @@ -524,8 +582,9 @@ func (o *Object) resetRelations() { }) } -// SessionToken returns token of the session -// within which object was created. +// SessionToken returns token of the session within which object was created. +// +// See also [Object.SetSessionToken]. func (o *Object) SessionToken() *session.Object { tokv2 := (*object.Object)(o).GetHeader().GetSessionToken() if tokv2 == nil { @@ -539,8 +598,9 @@ func (o *Object) SessionToken() *session.Object { return &res } -// SetSessionToken sets token of the session -// within which object was created. +// SetSessionToken sets token of the session within which object was created. +// +// See also [Object.SessionToken]. func (o *Object) SetSessionToken(v *session.Object) { o.setHeaderField(func(h *object.Header) { var tokv2 *v2session.Token @@ -555,6 +615,8 @@ func (o *Object) SetSessionToken(v *session.Object) { } // Type returns type of the object. +// +// See also [Object.SetType]. func (o *Object) Type() Type { return TypeFromV2( (*object.Object)(o). @@ -564,13 +626,15 @@ func (o *Object) Type() Type { } // SetType sets type of the object. +// +// See also [Object.Type]. func (o *Object) SetType(v Type) { o.setHeaderField(func(h *object.Header) { h.SetObjectType(v.ToV2()) }) } -// CutPayload returns Object w/ empty payload. +// CutPayload returns [Object] w/ empty payload. // // Changes of non-payload fields affect source object. func (o *Object) CutPayload() *Object { @@ -581,6 +645,7 @@ func (o *Object) CutPayload() *Object { return (*Object)(ov2) } +// HasParent checks if parent (split ID) is present. func (o *Object) HasParent() bool { return (*object.Object)(o). GetHeader(). @@ -598,11 +663,15 @@ func (o *Object) InitRelations() { } // Marshal marshals object into a protobuf binary form. +// +// See also [Object.Unmarshal]. func (o *Object) Marshal() ([]byte, error) { return (*object.Object)(o).StableMarshal(nil), nil } // Unmarshal unmarshals protobuf binary representation of object. +// +// See also [Object.Marshal]. func (o *Object) Unmarshal(data []byte) error { err := (*object.Object)(o).Unmarshal(data) if err != nil { @@ -613,11 +682,15 @@ func (o *Object) Unmarshal(data []byte) error { } // MarshalJSON encodes object to protobuf JSON format. +// +// See also [Object.UnmarshalJSON]. func (o *Object) MarshalJSON() ([]byte, error) { return (*object.Object)(o).MarshalJSON() } // UnmarshalJSON decodes object from protobuf JSON format. +// +// See also [Object.MarshalJSON]. func (o *Object) UnmarshalJSON(data []byte) error { err := (*object.Object)(o).UnmarshalJSON(data) if err != nil { diff --git a/object/range.go b/object/range.go index ea2238bc..99496176 100644 --- a/object/range.go +++ b/object/range.go @@ -4,17 +4,17 @@ import ( "github.com/nspcc-dev/neofs-api-go/v2/object" ) -// Range represents v2-compatible object payload range. +// Range represents v2 [object.Range] object payload range. type Range object.Range -// NewRangeFromV2 wraps v2 Range message to Range. +// NewRangeFromV2 wraps v2 [object.Range] message to [Range]. // -// Nil object.Range converts to nil. +// Nil [object.Range] converts to nil. func NewRangeFromV2(rV2 *object.Range) *Range { return (*Range)(rV2) } -// NewRange creates and initializes blank Range. +// NewRange creates and initializes blank [Range]. // // Defaults: // - offset: 0; @@ -23,29 +23,37 @@ func NewRange() *Range { return NewRangeFromV2(new(object.Range)) } -// ToV2 converts Range to v2 Range message. +// ToV2 converts [Range] to v2 [object.Range] message. // -// Nil Range converts to nil. +// Nil [Range] converts to nil. func (r *Range) ToV2() *object.Range { return (*object.Range)(r) } // GetLength returns payload range size. +// +// See also [Range.SetLength]. func (r *Range) GetLength() uint64 { return (*object.Range)(r).GetLength() } // SetLength sets payload range size. +// +// See also [Range.GetLength]. func (r *Range) SetLength(v uint64) { (*object.Range)(r).SetLength(v) } // GetOffset sets payload range offset from start. +// +// See also [Range.SetOffset]. func (r *Range) GetOffset() uint64 { return (*object.Range)(r).GetOffset() } // SetOffset gets payload range offset from start. +// +// See also [Range.GetOffset]. func (r *Range) SetOffset(v uint64) { (*object.Range)(r).SetOffset(v) } diff --git a/object/search.go b/object/search.go index 9d91714b..2b88423a 100644 --- a/object/search.go +++ b/object/search.go @@ -25,6 +25,7 @@ const ( MatchCommonPrefix ) +// ToV2 converts [SearchMatchType] to v2 [v2object.MatchType] enum value. func (m SearchMatchType) ToV2() v2object.MatchType { switch m { case MatchStringEqual: @@ -40,6 +41,7 @@ func (m SearchMatchType) ToV2() v2object.MatchType { } } +// SearchMatchFromV2 converts v2 [v2object.MatchType] to [SearchMatchType] enum value. func SearchMatchFromV2(t v2object.MatchType) (m SearchMatchType) { switch t { case v2object.MatchStringEqual: @@ -57,28 +59,28 @@ func SearchMatchFromV2(t v2object.MatchType) (m SearchMatchType) { return m } -// EncodeToString returns string representation of SearchMatchType. +// EncodeToString returns string representation of [SearchMatchType]. // // String mapping: -// - MatchStringEqual: STRING_EQUAL; -// - MatchStringNotEqual: STRING_NOT_EQUAL; -// - MatchNotPresent: NOT_PRESENT; -// - MatchCommonPrefix: COMMON_PREFIX; -// - MatchUnknown, default: MATCH_TYPE_UNSPECIFIED. +// - [MatchStringEqual]: STRING_EQUAL; +// - [MatchStringNotEqual]: STRING_NOT_EQUAL; +// - [MatchNotPresent]: NOT_PRESENT; +// - [MatchCommonPrefix]: COMMON_PREFIX; +// - [MatchUnknown], default: MATCH_TYPE_UNSPECIFIED. func (m SearchMatchType) EncodeToString() string { return m.ToV2().String() } -// String implements fmt.Stringer. +// String implements [fmt.Stringer]. // // String is designed to be human-readable, and its format MAY differ between -// SDK versions. String MAY return same result as EncodeToString. String MUST NOT +// SDK versions. String MAY return same result as [EncodeToString]. String MUST NOT // be used to encode ID into NeoFS protocol string. func (m SearchMatchType) String() string { return m.EncodeToString() } -// DecodeString parses SearchMatchType from a string representation. +// DecodeString parses [SearchMatchType] from a string representation. // It is a reverse action to EncodeToString(). // // Returns true if s was parsed successfully. @@ -98,6 +100,7 @@ type stringEncoder interface { EncodeToString() string } +// SearchFilter describes a single filter record. type SearchFilter struct { header filterKey value stringEncoder @@ -115,6 +118,7 @@ type filterKey struct { // enumeration of reserved filter keys. type filterKeyType int +// SearchFilters is type to describe a group of filters. type SearchFilters []SearchFilter const ( @@ -171,22 +175,27 @@ func (s staticStringer) EncodeToString() string { return string(s) } +// Header returns filter header value. func (f *SearchFilter) Header() string { return f.header.String() } +// Value returns filter value. func (f *SearchFilter) Value() string { return f.value.EncodeToString() } +// Operation returns filter operation value. func (f *SearchFilter) Operation() SearchMatchType { return f.op } +// NewSearchFilters constructs empty filter group. func NewSearchFilters() SearchFilters { return SearchFilters{} } +// NewSearchFiltersFromV2 converts slice of [v2object.SearchFilter] to [SearchFilters]. func NewSearchFiltersFromV2(v2 []v2object.SearchFilter) SearchFilters { filters := make(SearchFilters, 0, len(v2)) @@ -216,6 +225,7 @@ func (f *SearchFilters) addFilter(op SearchMatchType, keyTyp filterKeyType, key }) } +// AddFilter adds a filter to group by simple plain parameters. func (f *SearchFilters) AddFilter(header, value string, op SearchMatchType) { f.addFilter(op, 0, header, staticStringer(value)) } @@ -231,22 +241,27 @@ func (f *SearchFilters) addFlagFilter(keyTyp filterKeyType) { f.addFilter(MatchUnknown, keyTyp, "", staticStringer("")) } +// AddObjectVersionFilter adds a filter by version. func (f *SearchFilters) AddObjectVersionFilter(op SearchMatchType, v version.Version) { f.addReservedFilter(op, fKeyVersion, staticStringer(version.EncodeToString(v))) } +// AddObjectContainerIDFilter adds a filter by container id. func (f *SearchFilters) AddObjectContainerIDFilter(m SearchMatchType, id cid.ID) { f.addReservedFilter(m, fKeyContainerID, id) } +// AddObjectOwnerIDFilter adds a filter by object owner id. func (f *SearchFilters) AddObjectOwnerIDFilter(m SearchMatchType, id user.ID) { f.addReservedFilter(m, fKeyOwnerID, id) } +// AddNotificationEpochFilter adds a filter by epoch. This epoch is not about expiration, but about notification production. func (f *SearchFilters) AddNotificationEpochFilter(epoch uint64) { f.addFilter(MatchStringEqual, 0, v2object.SysAttributeTickEpoch, staticStringer(strconv.FormatUint(epoch, 10))) } +// ToV2 converts [SearchFilters] to [v2object.SearchFilter] slice. func (f SearchFilters) ToV2() []v2object.SearchFilter { result := make([]v2object.SearchFilter, len(f)) @@ -263,6 +278,7 @@ func (f *SearchFilters) addRootFilter() { f.addFlagFilter(fKeyPropRoot) } +// AddRootFilter adds filter by objects that have been created by a user explicitly. func (f *SearchFilters) AddRootFilter() { f.addRootFilter() } @@ -271,6 +287,7 @@ func (f *SearchFilters) addPhyFilter() { f.addFlagFilter(fKeyPropPhy) } +// AddPhyFilter adds filter by objects that are physically stored in the system. func (f *SearchFilters) AddPhyFilter() { f.addPhyFilter() } @@ -285,6 +302,7 @@ func (f *SearchFilters) AddObjectIDFilter(m SearchMatchType, id oid.ID) { f.addReservedFilter(m, fKeyObjectID, id) } +// AddSplitIDFilter adds filter by split ID. func (f *SearchFilters) AddSplitIDFilter(m SearchMatchType, id *SplitID) { f.addReservedFilter(m, fKeySplitID, staticStringer(id.String())) } @@ -294,12 +312,16 @@ func (f *SearchFilters) AddTypeFilter(m SearchMatchType, typ Type) { f.addReservedFilter(m, fKeyType, staticStringer(typ.EncodeToString())) } -// MarshalJSON encodes SearchFilters to protobuf JSON format. +// MarshalJSON encodes [SearchFilters] to protobuf JSON format. +// +// See also [SearchFilters.UnmarshalJSON]. func (f *SearchFilters) MarshalJSON() ([]byte, error) { return json.Marshal(f.ToV2()) } -// UnmarshalJSON decodes SearchFilters from protobuf JSON format. +// UnmarshalJSON decodes [SearchFilters] from protobuf JSON format. +// +// See also [SearchFilters.MarshalJSON]. func (f *SearchFilters) UnmarshalJSON(data []byte) error { var fsV2 []v2object.SearchFilter diff --git a/object/splitid.go b/object/splitid.go index 45b4a47c..8d890f2f 100644 --- a/object/splitid.go +++ b/object/splitid.go @@ -40,7 +40,7 @@ func NewSplitIDFromV2(v []byte) *SplitID { } } -// Parse converts UUIDv4 string representation into SplitID. +// Parse converts UUIDv4 string representation into [SplitID]. func (id *SplitID) Parse(s string) (err error) { id.uuid, err = uuid.Parse(s) if err != nil { @@ -50,7 +50,7 @@ func (id *SplitID) Parse(s string) (err error) { return nil } -// String returns UUIDv4 string representation of SplitID. +// String returns UUIDv4 string representation of [SplitID]. func (id *SplitID) String() string { if id == nil { return "" @@ -59,14 +59,14 @@ func (id *SplitID) String() string { return id.uuid.String() } -// SetUUID sets pre created UUID structure as SplitID. +// SetUUID sets pre created UUID structure as [SplitID]. func (id *SplitID) SetUUID(v uuid.UUID) { if id != nil { id.uuid = v } } -// ToV2 converts SplitID to a representation of SplitID in neofs-api v2. +// ToV2 converts [SplitID] to a representation of SplitID in neofs-api v2. // // Nil SplitID converts to nil. func (id *SplitID) ToV2() []byte { diff --git a/object/splitinfo.go b/object/splitinfo.go index e15cee5c..5538a33d 100644 --- a/object/splitinfo.go +++ b/object/splitinfo.go @@ -9,16 +9,17 @@ import ( oid "github.com/nspcc-dev/neofs-sdk-go/object/id" ) +// SplitInfo is an SDK representation of [object.SplitInfo]. type SplitInfo object.SplitInfo -// NewSplitInfoFromV2 wraps v2 SplitInfo message to SplitInfo. +// NewSplitInfoFromV2 wraps v2 [object.SplitInfo] message to [SplitInfo]. // // Nil object.SplitInfo converts to nil. func NewSplitInfoFromV2(v2 *object.SplitInfo) *SplitInfo { return (*SplitInfo)(v2) } -// NewSplitInfo creates and initializes blank SplitInfo. +// NewSplitInfo creates and initializes blank [SplitInfo]. // // Defaults: // - splitID: nil; @@ -28,22 +29,32 @@ func NewSplitInfo() *SplitInfo { return NewSplitInfoFromV2(new(object.SplitInfo)) } -// ToV2 converts SplitInfo to v2 SplitInfo message. +// ToV2 converts [SplitInfo] to v2 [object.SplitInfo] message. // // Nil SplitInfo converts to nil. func (s *SplitInfo) ToV2() *object.SplitInfo { return (*object.SplitInfo)(s) } +// SplitID returns [SplitID] if it has been set. +// +// See also [SplitInfo.SetSplitID]. func (s *SplitInfo) SplitID() *SplitID { return NewSplitIDFromV2( (*object.SplitInfo)(s).GetSplitID()) } +// SetSplitID sets split ID in object ID. It resets split ID if nil passed. +// +// See also [SplitInfo.SplitID]. func (s *SplitInfo) SetSplitID(v *SplitID) { (*object.SplitInfo)(s).SetSplitID(v.ToV2()) } +// LastPart returns last object ID, can be used to retrieve original object. +// The second return value is a flag, indicating if the last part is present. +// +// See also [SplitInfo.SetLastPart]. func (s SplitInfo) LastPart() (v oid.ID, isSet bool) { v2 := (object.SplitInfo)(s) @@ -56,6 +67,9 @@ func (s SplitInfo) LastPart() (v oid.ID, isSet bool) { return } +// SetLastPart sets the last object ID. +// +// See also [SplitInfo.LastPart]. func (s *SplitInfo) SetLastPart(v oid.ID) { var idV2 refs.ObjectID v.WriteToV2(&idV2) @@ -63,6 +77,10 @@ func (s *SplitInfo) SetLastPart(v oid.ID) { (*object.SplitInfo)(s).SetLastPart(&idV2) } +// Link returns a linker object ID. +// The second return value is a flag, indicating if the last part is present. +// +// See also [SplitInfo.SetLink]. func (s SplitInfo) Link() (v oid.ID, isSet bool) { v2 := (object.SplitInfo)(s) @@ -75,6 +93,9 @@ func (s SplitInfo) Link() (v oid.ID, isSet bool) { return } +// SetLink sets linker object ID. +// +// See also [SplitInfo.Link]. func (s *SplitInfo) SetLink(v oid.ID) { var idV2 refs.ObjectID v.WriteToV2(&idV2) @@ -82,10 +103,16 @@ func (s *SplitInfo) SetLink(v oid.ID) { (*object.SplitInfo)(s).SetLink(&idV2) } +// Marshal marshals [SplitInfo] into a protobuf binary form. +// +// See also [SplitInfo.Unmarshal]. func (s *SplitInfo) Marshal() ([]byte, error) { return (*object.SplitInfo)(s).StableMarshal(nil), nil } +// Unmarshal unmarshals protobuf binary representation of [SplitInfo]. +// +// See also [SplitInfo.Marshal]. func (s *SplitInfo) Unmarshal(data []byte) error { err := (*object.SplitInfo)(s).Unmarshal(data) if err != nil { @@ -96,11 +123,15 @@ func (s *SplitInfo) Unmarshal(data []byte) error { } // MarshalJSON implements json.Marshaler. +// +// See also [SplitInfo.UnmarshalJSON]. func (s *SplitInfo) MarshalJSON() ([]byte, error) { return (*object.SplitInfo)(s).MarshalJSON() } // UnmarshalJSON implements json.Unmarshaler. +// +// See also [SplitInfo.MarshalJSON]. func (s *SplitInfo) UnmarshalJSON(data []byte) error { err := (*object.SplitInfo)(s).UnmarshalJSON(data) if err != nil { diff --git a/object/tombstone.go b/object/tombstone.go index f55cdabe..5c92dee4 100644 --- a/object/tombstone.go +++ b/object/tombstone.go @@ -9,14 +9,14 @@ import ( // Tombstone represents v2-compatible tombstone structure. type Tombstone tombstone.Tombstone -// NewTombstoneFromV2 wraps v2 Tombstone message to Tombstone. +// NewTombstoneFromV2 wraps v2 [tombstone.Tombstone] message to [Tombstone]. // -// Nil tombstone.Tombstone converts to nil. +// Nil [tombstone.Tombstone] converts to nil. func NewTombstoneFromV2(tV2 *tombstone.Tombstone) *Tombstone { return (*Tombstone)(tV2) } -// NewTombstone creates and initializes blank Tombstone. +// NewTombstone creates and initializes blank [Tombstone]. // // Defaults: // - exp: 0; @@ -26,41 +26,45 @@ func NewTombstone() *Tombstone { return NewTombstoneFromV2(new(tombstone.Tombstone)) } -// ToV2 converts Tombstone to v2 Tombstone message. +// ToV2 converts [Tombstone] to v2 [tombstone.Tombstone] message. // -// Nil Tombstone converts to nil. +// Nil [Tombstone] converts to nil. func (t *Tombstone) ToV2() *tombstone.Tombstone { return (*tombstone.Tombstone)(t) } -// ExpirationEpoch returns the last NeoFS epoch -// number of the tombstone lifetime. +// ExpirationEpoch returns the last NeoFS epoch number of the tombstone lifetime. // -// See also SetExpirationEpoch. +// See also [Tombstone.SetExpirationEpoch]. func (t *Tombstone) ExpirationEpoch() uint64 { return (*tombstone.Tombstone)(t).GetExpirationEpoch() } -// SetExpirationEpoch sets the last NeoFS epoch -// number of the tombstone lifetime. +// SetExpirationEpoch sets the last NeoFS epoch number of the tombstone lifetime. // -// See also ExpirationEpoch. +// See also [Tombstone.ExpirationEpoch]. func (t *Tombstone) SetExpirationEpoch(v uint64) { (*tombstone.Tombstone)(t).SetExpirationEpoch(v) } // SplitID returns identifier of object split hierarchy. +// +// See also [Tombstone.SetSplitID]. func (t *Tombstone) SplitID() *SplitID { return NewSplitIDFromV2( (*tombstone.Tombstone)(t).GetSplitID()) } // SetSplitID sets identifier of object split hierarchy. +// +// See also [Tombstone.SplitID]. func (t *Tombstone) SetSplitID(v *SplitID) { (*tombstone.Tombstone)(t).SetSplitID(v.ToV2()) } // Members returns list of objects to be deleted. +// +// See also [Tombstone.SetMembers]. func (t *Tombstone) Members() []oid.ID { v2 := (*tombstone.Tombstone)(t) msV2 := v2.GetMembers() @@ -83,6 +87,8 @@ func (t *Tombstone) Members() []oid.ID { } // SetMembers sets list of objects to be deleted. +// +// See also [Tombstone.Members]. func (t *Tombstone) SetMembers(v []oid.ID) { var ms []refs.ObjectID @@ -107,22 +113,30 @@ func (t *Tombstone) SetMembers(v []oid.ID) { (*tombstone.Tombstone)(t).SetMembers(ms) } -// Marshal marshals Tombstone into a protobuf binary form. +// Marshal marshals [Tombstone] into a protobuf binary form. +// +// See also [Tombstone.Unmarshal]. func (t *Tombstone) Marshal() ([]byte, error) { return (*tombstone.Tombstone)(t).StableMarshal(nil), nil } -// Unmarshal unmarshals protobuf binary representation of Tombstone. +// Unmarshal unmarshals protobuf binary representation of [Tombstone]. +// +// See also [Tombstone.Marshal]. func (t *Tombstone) Unmarshal(data []byte) error { return (*tombstone.Tombstone)(t).Unmarshal(data) } -// MarshalJSON encodes Tombstone to protobuf JSON format. +// MarshalJSON encodes [Tombstone] to protobuf JSON format. +// +// See also [Tombstone.UnmarshalJSON]. func (t *Tombstone) MarshalJSON() ([]byte, error) { return (*tombstone.Tombstone)(t).MarshalJSON() } -// UnmarshalJSON decodes Tombstone from protobuf JSON format. +// UnmarshalJSON decodes [Tombstone] from protobuf JSON format. +// +// See also [Tombstone.MarshalJSON]. func (t *Tombstone) UnmarshalJSON(data []byte) error { return (*tombstone.Tombstone)(t).UnmarshalJSON(data) } diff --git a/object/type.go b/object/type.go index 52b80c11..58ea4117 100644 --- a/object/type.go +++ b/object/type.go @@ -4,6 +4,7 @@ import ( "github.com/nspcc-dev/neofs-api-go/v2/object" ) +// Type is an enumerator for possible object types. type Type object.Type const ( @@ -13,35 +14,37 @@ const ( TypeLock ) +// ToV2 converts [Type] to v2 [object.Type]. func (t Type) ToV2() object.Type { return object.Type(t) } +// TypeFromV2 converts v2 [object.Type] to [Type]. func TypeFromV2(t object.Type) Type { return Type(t) } -// EncodeToString returns string representation of Type. +// EncodeToString returns string representation of [Type]. // // String mapping: -// - TypeTombstone: TOMBSTONE; -// - TypeStorageGroup: STORAGE_GROUP; -// - TypeLock: LOCK; -// - TypeRegular, default: REGULAR. +// - [TypeTombstone]: TOMBSTONE; +// - [TypeStorageGroup]: STORAGE_GROUP; +// - [TypeLock]: LOCK; +// - [TypeRegular], default: REGULAR. func (t Type) EncodeToString() string { return t.ToV2().String() } -// String implements fmt.Stringer. +// String implements [fmt.Stringer]. // // String is designed to be human-readable, and its format MAY differ between -// SDK versions. String MAY return same result as EncodeToString. String MUST NOT +// SDK versions. String MAY return same result as [Type.EncodeToString]. String MUST NOT // be used to encode ID into NeoFS protocol string. func (t Type) String() string { return t.EncodeToString() } -// DecodeString parses Type from a string representation. +// DecodeString parses [Type] from a string representation. // It is a reverse action to EncodeToString(). // // Returns true if s was parsed successfully.