Commit fe751a15 authored by Kirill Smelkov's avatar Kirill Smelkov

go/zodb/fs1: Make it render more well in godoc

- Put dot after the subject,
- Indent lists,
- ...
parent 4eed282c
// Copyright (C) 2017 Nexedi SA and Contributors.
// Kirill Smelkov <kirr@nexedi.com>
// Copyright (C) 2017-2018 Nexedi SA and Contributors.
// Kirill Smelkov <kirr@nexedi.com>
//
// This program is free software: you can Use, Study, Modify and Redistribute
// it under the terms of the GNU General Public License version 3, or (at your
......@@ -218,7 +218,7 @@ const (
zIterPreloaded // data for this iteration was already preloaded
)
// NextTxn iterates to next/previous transaction record according to iteration direction
// NextTxn iterates to next/previous transaction record according to iteration direction.
func (zi *zIter) NextTxn(_ context.Context) (*zodb.TxnInfo, zodb.IDataIterator, error) {
// TODO err -> OpError("iter", tidmin..tidmax)
switch {
......@@ -246,7 +246,7 @@ func (zi *zIter) NextTxn(_ context.Context) (*zodb.TxnInfo, zodb.IDataIterator,
return &zi.iter.Txnh.TxnInfo, zi, nil
}
// NextData iterates to next data record and loads data content
// NextData iterates to next data record and loads data content.
func (zi *zIter) NextData(_ context.Context) (*zodb.DataInfo, error) {
// TODO err -> OpError("iter", tidmin..tidmax)
err := zi.iter.NextData()
......@@ -370,7 +370,7 @@ func (fs *FileStorage) findTxnRecord(r io.ReaderAt, tid zodb.Tid) (TxnHeader, er
return txnhFound, nil
}
// Iterate creates zodb-level iterator for tidMin..tidMax range
// Iterate creates zodb-level iterator for tidMin..tidMax range.
func (fs *FileStorage) Iterate(_ context.Context, tidMin, tidMax zodb.Tid) zodb.ITxnIterator {
// when iterating use IO optimized for sequential access
fsSeq := seqReadAt(fs.file)
......
// Copyright (C) 2017 Nexedi SA and Contributors.
// Kirill Smelkov <kirr@nexedi.com>
// Copyright (C) 2017-2018 Nexedi SA and Contributors.
// Kirill Smelkov <kirr@nexedi.com>
//
// This program is free software: you can Use, Study, Modify and Redistribute
// it under the terms of the GNU General Public License version 3, or (at your
......@@ -32,12 +32,12 @@ import (
"lab.nexedi.com/kirr/go123/xbytes"
)
// FileHeader represents header of whole data file
// FileHeader represents header of whole data file.
type FileHeader struct {
Magic [4]byte
}
// TxnHeader represents header of a transaction record
// TxnHeader represents header of a transaction record.
type TxnHeader struct {
Pos int64 // position of transaction start
LenPrev int64 // whole previous transaction record length (see EOF/error rules in Load)
......@@ -52,7 +52,7 @@ type TxnHeader struct {
workMem []byte
}
// DataHeader represents header of a data record
// DataHeader represents header of a data record.
type DataHeader struct {
Pos int64 // position of data record start
Oid zodb.Oid
......@@ -110,25 +110,26 @@ func (e *RecordError) Error() string {
}
// err creates RecordError for transaction located at txnh.Pos in f
// err creates RecordError for transaction located at txnh.Pos in f.
func (txnh *TxnHeader) err(f interface{}, subj string, err error) error {
return &RecordError{ioname(f), "transaction record", txnh.Pos, subj, err}
}
// err creates RecordError for data record located at dh.Pos in f
// err creates RecordError for data record located at dh.Pos in f.
func (dh *DataHeader) err(f interface{}, subj string, err error) error {
return &RecordError{ioname(f), "data record", dh.Pos, subj, err}
}
// ierr is an interface for something which can create errors.
//
// it is used by TxnHeader and DataHeader to create appropriate errors with their context.
type ierr interface {
err(f interface{}, subj string, err error) error
}
// errf is syntactic shortcut for err and fmt.Errorf
// errf is syntactic shortcut for err and fmt.Errorf.
func errf(f interface{}, e ierr, subj, format string, a ...interface{}) error {
return e.err(f, subj, fmt.Errorf(format, a...))
}
......@@ -169,12 +170,12 @@ func (txnh *TxnHeader) HeaderLen() int64 {
return TxnHeaderFixSize + int64(len(txnh.workMem))
}
// DataPos returns start position of data inside transaction record
// DataPos returns start position of data inside transaction record.
func (txnh *TxnHeader) DataPos() int64 {
return txnh.Pos + txnh.HeaderLen()
}
// DataLen returns length of all data inside transaction record container
// DataLen returns length of all data inside transaction record container.
func (txnh *TxnHeader) DataLen() int64 {
return txnh.Len - txnh.HeaderLen() - 8 /* trailer redundant length */
}
......@@ -329,7 +330,7 @@ func (txnh *TxnHeader) Load(r io.ReaderAt, pos int64, flags TxnLoadFlags) error
return err
}
// loadStrings makes sure strings that are part of transaction header are loaded
// loadStrings makes sure strings that are part of transaction header are loaded.
func (txnh *TxnHeader) loadStrings(r io.ReaderAt) error {
// XXX make it no-op if strings are already loaded?
......@@ -659,7 +660,8 @@ func (dh *DataHeader) loadNext(r io.ReaderAt, txnh *TxnHeader) error {
// LoadData loads data for the data record taking backpointers into account.
//
// NOTE on success dh state is changed to data header of original data transaction.
// On success dh state is changed to data header of original data transaction.
//
// NOTE "deleted" records are indicated via returning buf with .Data=nil without error.
func (dh *DataHeader) LoadData(r io.ReaderAt) (*mem.Buf, error) {
// scan via backpointers
......@@ -686,7 +688,7 @@ func (dh *DataHeader) LoadData(r io.ReaderAt) (*mem.Buf, error) {
// --- raw iteration ---
// Iter is combined 2-level iterator over transaction and data records
// Iter is combined 2-level iterator over transaction and data records.
type Iter struct {
R io.ReaderAt
Dir IterDir
......@@ -728,13 +730,13 @@ func (it *Iter) NextTxn(flags TxnLoadFlags) error {
return err
}
// NextData iterates to next data record header inside current transaction
// NextData iterates to next data record header inside current transaction.
func (it *Iter) NextData() error {
return it.Datah.LoadNext(it.R, &it.Txnh)
}
// Iterate creates Iter to iterate over r starting from posStart in direction dir
// Iterate creates Iter to iterate over r starting from posStart in direction dir.
func Iterate(r io.ReaderAt, posStart int64, dir IterDir) *Iter {
it := &Iter{R: r, Dir: dir, Txnh: TxnHeader{Pos: posStart}}
switch dir {
......
// Copyright (C) 2017 Nexedi SA and Contributors.
// Kirill Smelkov <kirr@nexedi.com>
// Copyright (C) 2017-2018 Nexedi SA and Contributors.
// Kirill Smelkov <kirr@nexedi.com>
//
// This program is free software: you can Use, Study, Modify and Redistribute
// it under the terms of the GNU General Public License version 3, or (at your
......@@ -83,7 +83,7 @@ const (
posValidMask uint64 = 1<<48 - 1 // 0x0000ffffffffffff
)
// IndexSaveError is the error type returned by index save routines
// IndexSaveError is the error type returned by index save routines.
type IndexSaveError struct {
Err error // error that occurred during the operation
}
......@@ -92,7 +92,7 @@ func (e *IndexSaveError) Error() string {
return "index save: " + e.Err.Error()
}
// Save saves index to a writer
// Save saves index to a writer.
func (fsi *Index) Save(w io.Writer) (err error) {
defer func() {
if err == nil {
......@@ -201,7 +201,7 @@ func (fsi *Index) SaveFile(path string) error {
return nil
}
// IndexLoadError is the error type returned by index load routines
// IndexLoadError is the error type returned by index load routines.
type IndexLoadError struct {
Filename string // present if used IO object was with .Name()
Pos int64
......@@ -220,7 +220,7 @@ func (e *IndexLoadError) Error() string {
return s
}
// LoadIndex loads index from a reader
// LoadIndex loads index from a reader.
func LoadIndex(r io.Reader) (fsi *Index, err error) {
var picklePos int64
defer func() {
......@@ -388,7 +388,7 @@ func treeEqual(a, b *fsb.Tree) bool {
// --- build index from FileStorage data ---
// IndexUpdateProgress is data sent by Index.Update to notify about progress
// IndexUpdateProgress is data sent by Index.Update to notify about progress.
type IndexUpdateProgress struct {
TopPos int64 // data range to update to; if = -1 -- till EOF
TxnIndexed int // # transactions read/indexed so far
......@@ -410,8 +410,9 @@ type IndexUpdateProgress struct {
// which position in data the index could be updated.
//
// On success returned error is nil and index.TopPos is set to either:
// - topPos (if it is != -1), or
// - r's position at which read got EOF (if topPos=-1).
//
// - topPos (if it is != -1), or
// - r's position at which read got EOF (if topPos=-1).
func (index *Index) Update(ctx context.Context, r io.ReaderAt, topPos int64, progress func(*IndexUpdateProgress)) (err error) {
defer xerr.Contextf(&err, "%sreindex %v..%v", ioprefix(r), index.TopPos, topPos)
......@@ -553,7 +554,7 @@ func indexCorrupt(f interface{}, format string, argv ...interface{}) *IndexCorru
return &IndexCorruptError{DataFileName: ioname(f), Detail: fmt.Sprintf(format, argv...)}
}
// IndexVerifyProgress is data sent by Index.Verify to notify about progress
// IndexVerifyProgress is data sent by Index.Verify to notify about progress.
type IndexVerifyProgress struct {
TxnTotal int // total # of transactions to verify; if = -1 -- whole data
TxnChecked int
......@@ -575,8 +576,9 @@ type IndexVerifyProgress struct {
// exactly the same as if it was build anew for data in range ..index.TopPos .
//
// Returned error is either:
// - of type *IndexCorruptError, when data in index was found not to match original data, or
// - any other error type representing e.g. IO error when reading original data or something else.
//
// - of type *IndexCorruptError, when data in index was found not to match original data, or
// - any other error type representing e.g. IO error when reading original data or something else.
func (index *Index) Verify(ctx context.Context, r io.ReaderAt, ntxn int, progress func(*IndexVerifyProgress)) (oidChecked map[zodb.Oid]struct{}, err error) {
defer func() {
if _, ok := err.(*IndexCorruptError); ok {
......@@ -672,7 +674,7 @@ func (index *Index) Verify(ctx context.Context, r io.ReaderAt, ntxn int, progres
return oidChecked, nil
}
// VerifyForFile checks index correctness against FileStorage data in file @ path
// VerifyForFile checks index correctness against FileStorage data in file @ path.
//
// See Verify for semantic description.
func (index *Index) VerifyForFile(ctx context.Context, path string, ntxn int, progress func(*IndexVerifyProgress)) (oidChecked map[zodb.Oid]struct{}, err error) {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment