*: Minor godoc cosmetics

my/my.go

-// Copyright (C) 2015-2017  Nexedi SA and Contributors.
+// Copyright (C) 2015-2019  Nexedi SA and Contributors.
 //                          Kirill Smelkov <kirr@nexedi.com>
 //
 // This program is free software: you can Use, Study, Modify and Redistribute
@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package my provides easy way to determine current function's name and other context
+// Package my provides easy way to determine current function's name and context.
 package my
 
 import (
@@ -37,15 +37,19 @@ func _myframe(nskip int) runtime.Frame {
 	return f
 }
 
-// FuncName returns name of currently running function (caller of FuncName())
+// FuncName returns name of currently running function.
+//
+// i.e. the name of FuncName caller.
+//
 // name is fully qualified package/name.function(.x)
 func FuncName() string {
 	f := _myframe(3)
 	return f.Function
 }
 
-// PkgName returns name of currently running function's package
-// package is fully qualified package/name
+// PkgName returns name of currently running function's package.
+//
+// package is fully qualified package/name.
 func PkgName() string {
 	f := _myframe(3)
 	myfunc := f.Function
@@ -63,19 +67,19 @@ func PkgName() string {
 	return myfunc[:iafterslash+idot]
 }
 
-// File returns path of currently running function's file
+// File returns path of currently running function's file.
 func File() string {
 	f := _myframe(3)
 	return f.File
 }
 
-// Line returns currently running function's line
+// Line returns currently running function's line.
 func Line() int {
 	f := _myframe(3)
 	return f.Line
 }
 
-// Frame returns currently running functions's frame
+// Frame returns currently running functions's frame.
 func Frame() runtime.Frame {
 	return _myframe(3)
 }

prog/prog.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -33,7 +33,7 @@ import (
 	"runtime/trace"
 )
 
-// Command describes one program subcommand
+// Command describes one program subcommand.
 type Command struct {
 	Name	string
 	Summary	string
@@ -41,10 +41,10 @@ type Command struct {
 	Main	func (argv []string)
 }
 
-// CommandRegistry is ordered collection of Commands
+// CommandRegistry is ordered collection of Commands.
 type CommandRegistry []Command
 
-// Lookup returns Command with corresponding name or nil
+// Lookup returns Command with corresponding name or nil.
 func (cmdv CommandRegistry) Lookup(command string) *Command {
 	for i := range cmdv {
 		if cmdv[i].Name == command {
@@ -54,17 +54,17 @@ func (cmdv CommandRegistry) Lookup(command string) *Command {
 	return nil
 }
 
-// HelpTopic describes one help topic
+// HelpTopic describes one help topic.
 type HelpTopic struct {
 	Name    string
 	Summary string
 	Text    string
 }
 
-// HelpRegistry is ordered collection of HelpTopics
+// HelpRegistry is ordered collection of HelpTopics.
 type HelpRegistry []HelpTopic
 
-// Lookup returns HelpTopic with corresponding name or nil
+// Lookup returns HelpTopic with corresponding name or nil.
 func (helpv HelpRegistry) Lookup(topic string) *HelpTopic {
 	for i := range helpv {
 		if helpv[i].Name == topic {
@@ -99,7 +99,7 @@ func Fatal(v ...interface{}) {
 	Exit(1)
 }
 
-// programExit is thrown when Exit or Fatal are called
+// programExit is thrown when Exit or Fatal are called.
 type programExit struct {
 	code int
 }
@@ -200,7 +200,7 @@ func (prog *MainProg) main() {
 	cmd.Main(argv)
 }
 
-// usage shows usage text for whole program
+// usage shows usage text for whole program.
 func (prog *MainProg) usage() {
 	w := os.Stderr
 	fmt.Fprintf(w,
@@ -257,7 +257,7 @@ Use "%s help [topic]" for more information about that topic.
 }
 
 
-// help shows general help or help for a command/topic
+// help shows general help or help for a command/topic.
 func (prog *MainProg) help(argv []string) {
 	if len(argv) < 2 {	// help topic ...
 		prog.usage()

tracing/cmd/gotrace/gotrace.go

-// Copyright (C) 2018  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2018-2019  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
@@ -62,7 +62,7 @@ import (
 	"lab.nexedi.com/kirr/go123/xerr"
 )
 
-// traceEvent represents 1 trace:event declaration
+// traceEvent represents 1 trace:event declaration.
 type traceEvent struct {
 	Pos  token.Position
 	Pkgt *Package // package this trace event is part of
@@ -84,14 +84,14 @@ type traceEvent struct {
 	*ast.FuncDecl
 }
 
-// traceImport represents 1 trace:import directive
+// traceImport represents 1 trace:import directive.
 type traceImport struct {
 	Pos     token.Position
 	PkgName string // "" if import name was not explicitly specified
 	PkgPath string
 }
 
-// traceImported represents 1 imported trace:event
+// traceImported represents 1 imported trace:event.
 type traceImported struct {
 	*traceEvent                   // imported event
 	ImportSpec  *traceImport      // imported via this spec
@@ -99,7 +99,7 @@ type traceImported struct {
 	ImportedAs  map[string]string // in context where some packages are imported as named (pkgpath -> pkgname)
 }
 
-// Package represents tracing-related information about a package
+// Package represents tracing-related information about a package.
 type Package struct {
 	Pkgi *loader.PackageInfo // original non-augmented package
 
@@ -228,7 +228,7 @@ func (p *Package) parseTraceImport(pos token.Position, text string) (*traceImpor
 	return &traceImport{Pos: pos, PkgName: pkgname, PkgPath: pkgpath}, nil
 }
 
-// progImporter is types.Importer that imports packages from loaded loader.Program
+// progImporter is types.Importer that imports packages from loaded loader.Program .
 type progImporter struct {
 	prog *loader.Program
 }
@@ -242,7 +242,7 @@ func (pi *progImporter) Import(path string) (*types.Package, error) {
 	return pkgi.Pkg, nil
 }
 
-// packageTrace returns tracing information about a package
+// packageTrace returns tracing information about a package.
 func packageTrace(prog *loader.Program, pkgi *loader.PackageInfo) (*Package, error) {
 	// prepare Package with typechecker ready to typecheck trace files
 	// (to get trace func argument types)
@@ -339,21 +339,21 @@ func packageTrace(prog *loader.Program, pkgi *loader.PackageInfo) (*Package, err
 	return p, nil
 }
 
-// byEventName provides []*traceEvent ordering by event name
+// byEventName provides []*traceEvent ordering by event name.
 type byEventName []*traceEvent
 
 func (v byEventName) Less(i, j int) bool { return v[i].Name.Name < v[j].Name.Name }
 func (v byEventName) Swap(i, j int)      { v[i], v[j] = v[j], v[i] }
 func (v byEventName) Len() int           { return len(v) }
 
-// byPkgPath provides []*traceImport ordering by package path
+// byPkgPath provides []*traceImport ordering by package path.
 type byPkgPath []*traceImport
 
 func (v byPkgPath) Less(i, j int) bool { return v[i].PkgPath < v[j].PkgPath }
 func (v byPkgPath) Swap(i, j int)      { v[i], v[j] = v[j], v[i] }
 func (v byPkgPath) Len() int           { return len(v) }
 
-// SplitTests splits package into main and test parts, each covering trace-related things accordingly
+// SplitTests splits package into main and test parts, each covering trace-related things accordingly.
 func (p *Package) SplitTests() (testPkg *Package) {
 	__ := *p
 	testPkg = &__
@@ -387,7 +387,7 @@ func (p *Package) SplitTests() (testPkg *Package) {
 
 // ----------------------------------------
 
-// Argv returns comma-separated argument-list
+// Argv returns comma-separated argument-list.
 func (te *traceEvent) Argv() string {
 	argv := []string{}
 
@@ -446,7 +446,7 @@ func (te *traceEvent) ArgvTypedRelativeTo(pkg *types.Package, importedAs map[str
 	return strings.Join(argv, ", ")
 }
 
-// NeedPkgv returns packages that are needed for argument types
+// NeedPkgv returns packages that are needed for argument types.
 func (te *traceEvent) NeedPkgv() []string {
 	pkgset := StrSet{ /*pkgpath*/ }
 	qf := func(pkg *types.Package) string {
@@ -463,7 +463,7 @@ func (te *traceEvent) NeedPkgv() []string {
 	return pkgset.Itemv()
 }
 
-// ImportSpec returns string representation of import spec
+// ImportSpec returns string representation of import spec.
 func (ti *traceImport) ImportSpec() string {
 	t := ti.PkgName
 	if t != "" {
@@ -473,7 +473,7 @@ func (ti *traceImport) ImportSpec() string {
 	return t
 }
 
-// traceEventCodeTmpl is code template generated for one trace event
+// traceEventCodeTmpl is code template generated for one trace event.
 var traceEventCodeTmpl = template.Must(template.New("traceevent").Parse(`
 // traceevent: {{.Name}}({{.ArgvTyped}})
 
@@ -512,14 +512,14 @@ func {{.Name}}_Attach(pg *tracing.ProbeGroup, probe func({{.ArgvTyped}})) *traci
 }
 `))
 
-// traceEventImportTmpl is code template generated for importing one trace event
+// traceEventImportTmpl is code template generated for importing one trace event.
 var traceEventImportTmpl = template.Must(template.New("traceimport").Parse(`
 {{/* function to attach a probe to tracepoint imported via go:linkname */ -}}
 //go:linkname {{.ImportSpec.PkgName}}_{{.Name}}_Attach {{.ImportSpec.PkgPath}}.{{.Name}}_Attach
 func {{.ImportSpec.PkgName}}_{{.Name}}_Attach(*tracing.ProbeGroup, func({{.ArgvTypedRelativeTo .ImporterPkg .ImportedAs}})) *tracing.Probe
 `))
 
-// traceEventImportCheckTmpl is code template generated to check consistency with one imported package
+// traceEventImportCheckTmpl is code template generated to check consistency with one imported package.
 var traceEventImportCheckTmpl = template.Must(template.New("traceimportcheck").Parse(`
 {{/* linking will fail if trace import code becomes out of sync wrt imported package */ -}}
 // rerun "gotrace gen" if you see link failure ↓↓↓
@@ -528,7 +528,7 @@ func {{.ImportSpec.PkgName}}_trace_exporthash()
 func init() { {{.ImportSpec.PkgName}}_trace_exporthash() }
 `))
 
-// magic begins all files generated by gotrace
+// magic begins all files generated by gotrace.
 const magic = "// Code generated by lab.nexedi.com/kirr/go123/tracing/cmd/gotrace; DO NOT EDIT.\n"
 
 // checkCanWrite checks whether it is safe to write to file at path.
@@ -553,7 +553,7 @@ func checkCanWrite(path string) error {
 	return nil
 }
 
-// writeFile writes data to a file at path after checking it is safe to write there
+// writeFile writes data to a file at path after checking it is safe to write there.
 func writeFile(path string, data []byte) error {
 	err := checkCanWrite(path)
 	if err != nil {
@@ -563,7 +563,7 @@ func writeFile(path string, data []byte) error {
 	return ioutil.WriteFile(path, data, 0666)
 }
 
-// removeFile make sure there is no file at path after checking it is safe to write to that file
+// removeFile make sure there is no file at path after checking it is safe to write to that file.
 func removeFile(path string) error {
 	err := checkCanWrite(path)
 	if err != nil {
@@ -597,7 +597,7 @@ type Program struct {
 	loaderConf *loader.Config
 }
 
-// NewProgram constructs new empty Program ready to load packages according to specified build context
+// NewProgram constructs new empty Program ready to load packages according to specified build context.
 func NewProgram(ctxt *build.Context, cwd string) *Program {
 	// adjust build context to filter-out ztrace* files when discovering packages
 	//

tracing/cmd/gotrace/util.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -26,7 +26,7 @@ import (
 	"sort"
 )
 
-// Buffer is bytes.Buffer + syntatic sugar
+// Buffer is bytes.Buffer + syntatic sugar.
 type Buffer struct {
 	bytes.Buffer
 }
@@ -36,7 +36,7 @@ func (b *Buffer) emit(format string, argv ...interface{}) {
 }
 
 
-// StrSet is set<string>
+// StrSet is set<string>.
 type StrSet map[string]struct{}
 
 func (s StrSet) Add(itemv ...string) {
@@ -54,7 +54,7 @@ func (s StrSet) Has(item string) bool {
 	return has
 }
 
-// Itemv returns ordered slice of set items
+// Itemv returns ordered slice of set items.
 func (s StrSet) Itemv() []string {
 	itemv := make([]string, 0, len(s))
 	for item := range s {

tracing/tracing.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -225,7 +225,7 @@ func Lock() {
 	xruntime.RaceIgnoreBegin()
 }
 
-// Unlock is the opposite to Lock and returns with the world resumed
+// Unlock is the opposite to Lock and returns with the world resumed.
 func Unlock() {
 	xruntime.RaceIgnoreEnd()
 	atomic.StoreInt32(&traceLocked, 0)
@@ -233,14 +233,14 @@ func Unlock() {
 	traceMu.Unlock()
 }
 
-// verifyLocked makes sure tracing is locked and panics otherwise
+// verifyLocked makes sure tracing is locked and panics otherwise.
 func verifyLocked() {
 	if atomic.LoadInt32(&traceLocked) == 0 {
 		panic("tracing must be locked")
 	}
 }
 
-// verifyUnlocked makes sure tracing is not locked and panics otherwise
+// verifyUnlocked makes sure tracing is not locked and panics otherwise.
 func verifyUnlocked() {
 	if atomic.LoadInt32(&traceLocked) != 0 {
 		panic("tracing must be unlocked")
@@ -248,7 +248,7 @@ func verifyUnlocked() {
 }
 
 
-// Probe describes one probe attached to a tracepoint
+// Probe describes one probe attached to a tracepoint.
 type Probe struct {
 	// NOTE .next must come first as probe list header is only 1 word and
 	// is treated as *Probe on probe attach/detach - accessing/modifying its .next

xcontainer/list/list.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -40,20 +40,21 @@ type Head struct {
 func (h *Head) Next() *Head { return h.next }
 func (h *Head) Prev() *Head { return h.prev }
 
-// Init initializes a head making it point to itself via .next and .prev
+// Init initializes a head making it point to itself via .next and .prev .
 func (h *Head) Init() {
 	h.next = h
 	h.prev = h
 }
 
-// Delete deletes h from its list
+// Delete deletes h from its list.
 func (h *Head) Delete() {
 	h.next.prev = h.prev
 	h.prev.next = h.next
 	h.Init()
 }
 
-// MoveBefore moves a to be before b
+// MoveBefore moves a to be before b.
+//
 // XXX ok to move if a was not previously on the list?
 func (a *Head) MoveBefore(b *Head) {
 	a.Delete()

xflag/doc.go

-// Package xflag provides addons to standard package flag
+// Package xflag provides addons to standard package flag.
 package xflag

xfmt/fmt.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -46,28 +46,29 @@ const (
 	hexdigits = "0123456789abcdef"
 )
 
-// Stringer is interface for natively formatting a value representation via xfmt
+// Stringer is interface for natively formatting a value representation via xfmt.
 type Stringer interface {
 	// XFmtString method is used to append formatted value to destination buffer
 	// The grown buffer have to be returned
 	XFmtString(b []byte) []byte
 }
 
-// Buffer provides syntactic sugar for formatting mimicking fmt.Printf style
+// Buffer provides syntactic sugar for formatting mimicking fmt.Printf style.
+//
 // XXX combine with bytes.Buffer ?
 type Buffer []byte
 
-// Reset empties the buffer keeping underlying storage for future formattings
+// Reset empties the buffer keeping underlying storage for future formattings.
 func (b *Buffer) Reset() {
 	*b = (*b)[:0]
 }
 
-// Bytes returns buffer storage as []byte
+// Bytes returns buffer storage as []byte.
 func (b Buffer) Bytes() []byte {
 	return []byte(b)
 }
 
-// Append appends to b formatted x
+// Append appends to b formatted x.
 //
 // NOTE sadly since x is interface it makes real value substituted to it
 // 	escape to heap (not so a problem since usually they already are) but then also
@@ -78,54 +79,54 @@ func Append(b []byte, x Stringer) []byte {
 	return x.XFmtString(b)
 }
 
-// V, similarly to %v, adds x formatted by default rules
+// V, similarly to %v, adds x formatted by default rules.
 func (b *Buffer) V(x Stringer) *Buffer {
 	*b = Append(*b, x)
 	return b
 }
 
-// S appends string formatted by %s
+// S appends string formatted by %s.
 func (b *Buffer) S(s string) *Buffer {
 	*b = append(*b, s...)
 	return b
 }
 
-// Sb appends []byte formatted by %s
+// Sb appends []byte formatted by %s.
 func (b *Buffer) Sb(x []byte) *Buffer {
 	*b = append(*b, x...)
 	return b
 }
 
-// Q appends string formatted by %q
+// Q appends string formatted by %q.
 func (b *Buffer) Q(s string) *Buffer {
 	*b = strconv.AppendQuote(*b, s)
 	return b
 }
 
-// Qb appends []byte formatted by %q
+// Qb appends []byte formatted by %q.
 func (b *Buffer) Qb(s []byte) *Buffer {
 	*b = strconv.AppendQuote(*b, mem.String(s))
 	return b
 }
 
-// Qcb appends byte formatted by %q
+// Qcb appends byte formatted by %q.
 func (b *Buffer) Qcb(c byte) *Buffer {
 	return b.Qc(rune(c))
 }
 
-// Qc appends rune formatted by %q
+// Qc appends rune formatted by %q.
 func (b *Buffer) Qc(c rune) *Buffer {
 	*b = strconv.AppendQuoteRune(*b, c)
 	return b
 }
 
-// Cb appends byte formatted by %c
+// Cb appends byte formatted by %c.
 func (b *Buffer) Cb(c byte) *Buffer {
 	*b = append(*b, c)
 	return b
 }
 
-// AppendRune appends to b UTF-8 encoding of r
+// AppendRune appends to b UTF-8 encoding of r.
 func AppendRune(b []byte, r rune) []byte {
 	l := len(b)
 	b = xbytes.Grow(b, utf8.UTFMax)
@@ -133,31 +134,31 @@ func AppendRune(b []byte, r rune) []byte {
 	return b[:l+n]
 }
 
-// C appends rune formatted by %c
+// C appends rune formatted by %c.
 func (b *Buffer) C(r rune) *Buffer {
 	*b = AppendRune(*b, r)
 	return b
 }
 
-// D appends int formatted by %d
+// D appends int formatted by %d.
 func (b *Buffer) D(i int) *Buffer {
 	*b = strconv.AppendInt(*b, int64(i), 10)
 	return b
 }
 
-// D64 appends int64 formatted by %d
+// D64 appends int64 formatted by %d.
 func (b *Buffer) D64(i int64) *Buffer {
 	*b = strconv.AppendInt(*b, i, 10)
 	return b
 }
 
-// X appends int formatted by %x
+// X appends int formatted by %x.
 func (b *Buffer) X(i int) *Buffer {
 	*b = strconv.AppendInt(*b, int64(i), 16)
 	return b
 }
 
-// AppendHex appends to b hex representation of x
+// AppendHex appends to b hex representation of x.
 func AppendHex(b []byte, x []byte) []byte {
 	lx := hex.EncodedLen(len(x))
 	lb := len(b)
@@ -166,20 +167,20 @@ func AppendHex(b []byte, x []byte) []byte {
 	return b
 }
 
-// Xb appends []byte formatted by %x
+// Xb appends []byte formatted by %x.
 func (b *Buffer) Xb(x []byte) *Buffer {
 	*b = AppendHex(*b, x)
 	return b
 }
 
-// Xs appends string formatted by %x
+// Xs appends string formatted by %x.
 func (b *Buffer) Xs(x string) *Buffer {
 	return b.Xb(mem.Bytes(x))
 }
 
 // TODO XX = %X
 
-// AppendHex016 appends to b x formatted 16-character hex string
+// AppendHex016 appends to b x formatted 16-character hex string.
 func AppendHex016(b []byte, x uint64) []byte {
         // like sprintf("%016x") but faster and less allocations
 	l := len(b)
@@ -192,7 +193,7 @@ func AppendHex016(b []byte, x uint64) []byte {
 	return b
 }
 
-// X016, similarly to %016x, adds hex representation of uint64 x
+// X016, similarly to %016x, adds hex representation of uint64 x.
 func (b *Buffer) X016(x uint64) *Buffer {
 	*b = AppendHex016(*b, x)
 	return b

xfmt/python.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -29,12 +29,12 @@ import (
 	"lab.nexedi.com/kirr/go123/xbytes"
 )
 
-// AppendQuotePy appends to buf Python quoting of s
+// AppendQuotePy appends to buf Python quoting of s.
 func AppendQuotePy(buf []byte, s string) []byte {
 	return AppendQuotePyBytes(buf, mem.Bytes(s))
 }
 
-// AppendQuotePyBytes appends to buf Python quoting of b
+// AppendQuotePyBytes appends to buf Python quoting of b.
 func AppendQuotePyBytes(buf, b []byte) []byte {
 	// smartquotes: choose ' or " as quoting character
 	// https://github.com/python/cpython/blob/v2.7.13-116-g1aa1803b3d/Objects/stringobject.c#L947
@@ -109,13 +109,13 @@ func AppendQuotePyBytes(buf, b []byte) []byte {
 }
 
 
-// Qpy appends string quoted as Python would do
+// Qpy appends string quoted as Python would do.
 func (b *Buffer) Qpy(s string) *Buffer {
 	*b = AppendQuotePy(*b, s)
 	return b
 }
 
-// Qpyb appends []byte quoted as Python would do
+// Qpyb appends []byte quoted as Python would do.
 func (b *Buffer) Qpyb(x []byte) *Buffer {
 	*b = AppendQuotePyBytes(*b, x)
 	return b
@@ -123,7 +123,7 @@ func (b *Buffer) Qpyb(x []byte) *Buffer {
 
 // TODO Qpyc?
 
-// Qpycb appends byte quoted as Python would do for a single-character string
+// Qpycb appends byte quoted as Python would do for a single-character string.
 func (b *Buffer) Qpycb(c byte) *Buffer {
 	*b = AppendQuotePyBytes(*b, []byte{c})	// does not escape
 	return b

xio/xio.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -39,7 +39,7 @@ func (cr *CountedReader) InputOffset() int64 {
 	return cr.nread
 }
 
-// CountReader wraps r with CountedReader
+// CountReader wraps r with CountedReader.
 func CountReader(r io.Reader) *CountedReader {
 	return &CountedReader{r, 0}
 }

xmath/math18.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -21,7 +21,7 @@
 
 package xmath
 
-// CeilPow2 returns minimal y >= x, such that y = 2^i
+// CeilPow2 returns minimal y >= x, such that y = 2^i.
 func CeilPow2(x uint64) uint64 {
 	if x == 0 {
 		return x

xmath/math19.go

-// Copyright (C) 2017  Nexedi SA and Contributors.
-//                     Kirill Smelkov <kirr@nexedi.com>
+// Copyright (C) 2017-2019  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
@@ -19,14 +19,14 @@
 
 // +build go1.9
 
-// Package xmath provides addons to std math package
+// Package xmath provides addons to std math package.
 package xmath
 
 import (
 	"math/bits"
 )
 
-// CeilPow2 returns minimal y >= x, such that y = 2^i
+// CeilPow2 returns minimal y >= x, such that y = 2^i.
 func CeilPow2(x uint64) uint64 {
 	switch bits.OnesCount64(x) {
 	case 0, 1:
@@ -36,7 +36,7 @@ func CeilPow2(x uint64) uint64 {
 	}
 }
 
-// CeilLog2 returns minimal i: 2^i >= x
+// CeilLog2 returns minimal i: 2^i >= x.
 func CeilLog2(x uint64) int {
 	switch bits.OnesCount64(x) {
 	case 0:
@@ -48,7 +48,7 @@ func CeilLog2(x uint64) int {
 	}
 }
 
-// FloorLog2 returns maximal i: 2^i <= x
+// FloorLog2 returns maximal i: 2^i <= x.
 //
 // x=0 gives -> -1.
 func FloorLog2(x uint64) int {

xnet/net.go

-// Copyright (C) 2017-2018  Nexedi SA and Contributors.
+// Copyright (C) 2017-2019  Nexedi SA and Contributors.
 //                          Kirill Smelkov <kirr@nexedi.com>
 //
 // This program is free software: you can Use, Study, Modify and Redistribute
@@ -31,7 +31,7 @@ import (
 
 // Networker is interface representing access-point to a streaming network.
 type Networker interface {
-	// Network returns name of the network
+	// Network returns name of the network.
 	Network() string
 
 	// Name returns name of the access-point on the network.

xnet/trace.go

-// Copyright (C) 2017-2018  Nexedi SA and Contributors.
+// Copyright (C) 2017-2019  Nexedi SA and Contributors.
 //                          Kirill Smelkov <kirr@nexedi.com>
 //
 // This program is free software: you can Use, Study, Modify and Redistribute
@@ -25,7 +25,7 @@ import (
 	"net"
 )
 
-// NetTrace wraps underlying networker with IO tracing layer
+// NetTrace wraps underlying networker with IO tracing layer.
 //
 // Tracing is done via calling trace func right after corresponding networking
 // event happenned.  No synchronization for notification is performed - if one
@@ -45,7 +45,7 @@ func NetTrace(inner Networker, tracer Tracer) Networker {
 	return &netTrace{inner, tracer}
 }
 
-// Tracer is the interface that needs to be implemented by network trace receivers
+// Tracer is the interface that needs to be implemented by network trace receivers.
 type Tracer interface {
 	TraceNetDial(*TraceDial)
 	TraceNetConnect(*TraceConnect)
@@ -66,13 +66,13 @@ type TraceConnect struct {
 	Dialed   string
 }
 
-// TraceListen is event corresponding to network listening
+// TraceListen is event corresponding to network listening.
 type TraceListen struct {
 	// XXX also put networker?
 	Laddr net.Addr
 }
 
-// TraceTx is event corresponding to network transmission
+// TraceTx is event corresponding to network transmission.
 type TraceTx struct {
 	// XXX also put network somehow?
 	Src, Dst net.Addr
@@ -114,7 +114,7 @@ func (nt *netTrace) Listen(laddr string) (net.Listener, error) {
 	return &netTraceListener{nt, l}, nil
 }
 
-// netTraceListener wraps net.Listener to wrap accepted connections with traceConn
+// netTraceListener wraps net.Listener to wrap accepted connections with traceConn.
 type netTraceListener struct {
 	nt           *netTrace
 	net.Listener
@@ -128,7 +128,7 @@ func (ntl *netTraceListener) Accept() (net.Conn, error) {
 	return &traceConn{ntl.nt, c}, nil
 }
 
-// traceConn wraps net.Conn and notifies tracer on Writes
+// traceConn wraps net.Conn and notifies tracer on Writes.
 type traceConn struct {
 	nt       *netTrace
 	net.Conn

xruntime/xruntime.go

-// Copyright (C) 2015-2017  Nexedi SA and Contributors.
+// Copyright (C) 2015-2019  Nexedi SA and Contributors.
 //                          Kirill Smelkov <kirr@nexedi.com>
 //
 // This program is free software: you can Use, Study, Modify and Redistribute
@@ -17,15 +17,16 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package xruntime provides addons to standard package runtime
+// Package xruntime provides addons to standard package runtime.
 package xruntime
 
 import (
 	"runtime"
 )
 
-// Traceback returns current calling traceback as []runtime.Frame
-// nskip meaning: the same as in runtime.Callers()
+// Traceback returns current calling traceback as []runtime.Frame .
+//
+// nskip meaning: the same as in runtime.Callers() .
 func Traceback(nskip int) []runtime.Frame {
 	// all callers
 	var pcv = []uintptr{0}

xstrings/xstrings.go

-// Copyright (C) 2015-2017  Nexedi SA and Contributors.
+// Copyright (C) 2015-2019  Nexedi SA and Contributors.
 //                          Kirill Smelkov <kirr@nexedi.com>
 //
 // This program is free software: you can Use, Study, Modify and Redistribute
@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package xstrings provides addons to standard package strings
+// Package xstrings provides addons to standard package strings.
 package xstrings
 
 import (
@@ -25,7 +25,9 @@ import (
 	"strings"
 )
 
-// split string into lines. The last line, if it is empty, is omitted from the result
+// SplitLines splits string into lines.
+//
+// The last line, if it is empty, is omitted from the result.
 // (rationale is: string.Split("hello\nworld\n", "\n") -> ["hello", "world", ""])
 func SplitLines(s, sep string) []string {
 	sv := strings.Split(s, sep)
@@ -36,7 +38,7 @@ func SplitLines(s, sep string) []string {
 	return sv
 }
 
-// split string by sep and expect exactly 2 parts
+// Split2 splits string by sep and expects exactly 2 parts.
 func Split2(s, sep string) (s1, s2 string, err error) {
 	parts := strings.Split(s, sep)
 	if len(parts) != 2 {
@@ -45,7 +47,11 @@ func Split2(s, sep string) (s1, s2 string, err error) {
 	return parts[0], parts[1], nil
 }
 
-// (head+sep+tail) -> head, tail
+// HeadTail splits string into head & tail.
+//
+// (head+sep+tail) -> head, tail.
+//
+// Note: tail may contain sep.
 func HeadTail(s, sep string) (head, tail string, err error) {
 	parts := strings.SplitN(s, sep, 2)
 	if len(parts) != 2 {