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

- Put dot after the subject,
- Indent lists,
- ...

go/zodb/storage/fs1/filestorage.go

-// 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)

go/zodb/storage/fs1/format.go

-// 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 {

go/zodb/storage/fs1/index.go

-// 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) {