[#948] engine: Fix comments of object listing with cursor

Signed-off-by: Alex Vanin <alexey@nspcc.ru>

pkg/local_object_storage/engine/list.go

@@ -20,14 +20,14 @@ type ListWithCursorPrm struct {
 	cursor *Cursor
 }
 
-// WithCount sets maximum amount of addresses that ListWithCursor can return.
+// WithCount sets maximum amount of addresses that ListWithCursor should return.
 func (p *ListWithCursorPrm) WithCount(count uint32) *ListWithCursorPrm {
 	p.count = count
 	return p
 }
 
 // WithCursor sets cursor for ListWithCursor operation. For initial request
-// ignore this param or use nil value. For continues requests, use  value
+// ignore this param or use nil value. For consecutive requests, use  value
 // from ListWithCursorRes.
 func (p *ListWithCursorPrm) WithCursor(cursor *Cursor) *ListWithCursorPrm {
 	p.cursor = cursor
@@ -50,10 +50,13 @@ func (l ListWithCursorRes) Cursor() *Cursor {
 	return l.cursor
 }
 
-// ListWithCursor lists physical objects available in specified shard starting
+// ListWithCursor lists physical objects available in engine starting
 // from cursor. Includes regular,tombstone and storage group objects.
 // Does not include inhumed objects. Use cursor value from response
 // for consecutive requests.
+//
+// Returns ErrEndOfListing if there are no more objects to return or count
+// parameter set to zero.
 func (e *StorageEngine) ListWithCursor(prm *ListWithCursorPrm) (*ListWithCursorRes, error) {
 	result := make([]*object.Address, 0, prm.count)
 

pkg/local_object_storage/metabase/list.go

@@ -18,14 +18,14 @@ type ListPrm struct {
 	cursor *Cursor
 }
 
-// WithCount sets maximum amount of addresses that ListWithCursor can return.
+// WithCount sets maximum amount of addresses that ListWithCursor should return.
 func (l *ListPrm) WithCount(count uint32) *ListPrm {
 	l.count = int(count)
 	return l
 }
 
 // WithCursor sets cursor for ListWithCursor operation. For initial request
-// ignore this param or use nil value. For continues requests, use value
+// ignore this param or use nil value. For consecutive requests, use value
 // from ListRes.
 func (l *ListPrm) WithCursor(cursor *Cursor) *ListPrm {
 	l.cursor = cursor
@@ -54,9 +54,12 @@ const (
 	cursorBucketSG
 )
 
-// ListWithCursor lists physical objects available in metabase. Includes regular,
+// ListWithCursor lists physical objects available in metabase starting from
-// tombstone and storage group objects. Does not include inhumed objects. Use
+// cursor. Includes regular, tombstone and storage group objects. Does not
-// cursor value from response for consecutive requests.
+// include inhumed objects. Use cursor value from response for consecutive requests.
+//
+// Returns ErrEndOfListing if there are no more objects to return or count
+// parameter set to zero.
 func ListWithCursor(db *DB, count uint32, cursor *Cursor) ([]*object.Address, *Cursor, error) {
 	r, err := db.ListWithCursor(new(ListPrm).WithCount(count).WithCursor(cursor))
 	if err != nil {
@@ -66,9 +69,12 @@ func ListWithCursor(db *DB, count uint32, cursor *Cursor) ([]*object.Address, *C
 	return r.AddressList(), r.Cursor(), nil
 }
 
-// ListWithCursor lists physical objects available in metabase. Includes regular,
+// ListWithCursor lists physical objects available in metabase starting from
-// tombstone and storage group objects. Does not include inhumed objects. Use
+// cursor. Includes regular, tombstone and storage group objects. Does not
-// cursor value from response for consecutive requests.
+// include inhumed objects. Use cursor value from response for consecutive requests.
+//
+// Returns ErrEndOfListing if there are no more objects to return or count
+// parameter set to zero.
 func (db *DB) ListWithCursor(prm *ListPrm) (res *ListRes, err error) {
 	err = db.boltDB.View(func(tx *bbolt.Tx) error {
 		res = new(ListRes)

pkg/local_object_storage/shard/list.go

@@ -34,14 +34,14 @@ type ListWithCursorRes struct {
 	cursor   *Cursor
 }
 
-// WithCount sets maximum amount of addresses that ListWithCursor can return.
+// WithCount sets maximum amount of addresses that ListWithCursor should return.
 func (p *ListWithCursorPrm) WithCount(count uint32) *ListWithCursorPrm {
 	p.count = count
 	return p
 }
 
 // WithCursor sets cursor for ListWithCursor operation. For initial request,
-// ignore this param or use nil value. For continues requests, use value
+// ignore this param or use nil value. For consecutive requests, use value
 // from ListWithCursorRes.
 func (p *ListWithCursorPrm) WithCursor(cursor *Cursor) *ListWithCursorPrm {
 	p.cursor = cursor
@@ -108,6 +108,9 @@ func ListContainers(s *Shard) ([]*cid.ID, error) {
 // ListWithCursor lists physical objects available in shard starting from
 // cursor. Includes regular, tombstone and storage group objects. Does not
 // include inhumed objects. Use cursor value from response for consecutive requests.
+//
+// Returns ErrEndOfListing if there are no more objects to return or count
+// parameter set to zero.
 func (s *Shard) ListWithCursor(prm *ListWithCursorPrm) (*ListWithCursorRes, error) {
 	metaPrm := new(meta.ListPrm).WithCount(prm.count).WithCursor(prm.cursor)
 	res, err := s.metaBase.ListWithCursor(metaPrm)
@@ -124,6 +127,9 @@ func (s *Shard) ListWithCursor(prm *ListWithCursorPrm) (*ListWithCursorRes, erro
 // ListWithCursor lists physical objects available in shard starting from
 // cursor. Includes regular, tombstone and storage group objects. Does not
 // include inhumed objects. Use cursor value from response for consecutive requests.
+//
+// Returns ErrEndOfListing if there are no more objects to return or count
+// parameter set to zero.
 func ListWithCursor(s *Shard, count uint32, cursor *Cursor) ([]*object.Address, *Cursor, error) {
 	prm := new(ListWithCursorPrm).WithCount(count).WithCursor(cursor)
 	res, err := s.ListWithCursor(prm)