Merge pull request #486 from tuneinsight/doc-formatting

[Road to V6] Godoc Formatting Cleanup

README.md

@@ -108,6 +108,17 @@ RLWE --> MHE([MHE])
 MHE --> MHEInt
 ```
 
+### Documentation
+
+The full documentation of the individual packages can be browsed as a web page using official
+Golang documentation rendering tool `pkgsite`
+
+```bash
+$ go install golang.org/x/pkgsite/cmd/pkgsite@latest
+$ cd lattigo
+$ pkgsite -open .
+```
+
 ## Versions and Roadmap
 
 The Lattigo library was originally exclusively developed by the EPFL Laboratory for Data Security

core/rgsw/elements.go

@@ -23,7 +23,7 @@ func (ct Ciphertext) LevelP() int {
 	return ct.Value[0].LevelP()
 }
 
-// NewCiphertext allocates a new RGSW ciphertext in the NTT domain.
+// NewCiphertext allocates a new RGSW [Ciphertext] in the NTT domain.
 func NewCiphertext(params rlwe.Parameters, levelQ, levelP, BaseTwoDecomposition int) (ct *Ciphertext) {
 	return &Ciphertext{
 		Value: [2]rlwe.GadgetCiphertext{
@@ -38,15 +38,15 @@ func (ct Ciphertext) BinarySize() int {
 	return ct.Value[0].BinarySize() + ct.Value[1].BinarySize()
 }
 
-// WriteTo writes the object on an io.Writer. It implements the io.WriterTo
+// WriteTo writes the object on an [io.Writer]. It implements the [io.WriterTo]
 // interface, and will write exactly object.BinarySize() bytes on w.
 //
-// Unless w implements the buffer.Writer interface (see lattigo/utils/buffer/writer.go),
-// it will be wrapped into a bufio.Writer. Since this requires allocations, it
-// is preferable to pass a buffer.Writer directly:
+// Unless w implements the [buffer.Writer] interface (see lattigo/utils/buffer/writer.go),
+// it will be wrapped into a [bufio.Writer]. Since this requires allocations, it
+// is preferable to pass a [buffer.Writer] directly:
 //
-//   - When writing multiple times to a io.Writer, it is preferable to first wrap the
-//     io.Writer in a pre-allocated bufio.Writer.
+//   - When writing multiple times to a [io.Writer], it is preferable to first wrap the
+//     [io.Writer] in a pre-allocated [bufio.Writer].
 //   - When writing to a pre-allocated var b []byte, it is preferable to pass
 //     buffer.NewBuffer(b) as w (see lattigo/utils/buffer/buffer.go).
 func (ct Ciphertext) WriteTo(w io.Writer) (n int64, err error) {
@@ -66,15 +66,15 @@ func (ct Ciphertext) WriteTo(w io.Writer) (n int64, err error) {
 	}
 }
 
-// ReadFrom reads on the object from an io.Writer. It implements the
-// io.ReaderFrom interface.
+// ReadFrom reads on the object from an [io.Writer]. It implements the
+// [io.ReaderFrom] interface.
 //
-// Unless r implements the buffer.Reader interface (see see lattigo/utils/buffer/reader.go),
-// it will be wrapped into a bufio.Reader. Since this requires allocation, it
-// is preferable to pass a buffer.Reader directly:
+// Unless r implements the [buffer.Reader] interface (see see lattigo/utils/buffer/reader.go),
+// it will be wrapped into a [bufio.Reader]. Since this requires allocation, it
+// is preferable to pass a [buffer.Reader] directly:
 //
-//   - When reading multiple values from a io.Reader, it is preferable to first
-//     first wrap io.Reader in a pre-allocated bufio.Reader.
+//   - When reading multiple values from a [io.Reader], it is preferable to first
+//     first wrap [io.Reader] in a pre-allocated [bufio.Reader].
 //   - When reading from a var b []byte, it is preferable to pass a buffer.NewBuffer(b)
 //     as w (see lattigo/utils/buffer/buffer.go).
 func (ct *Ciphertext) ReadFrom(r io.Reader) (n int64, err error) {
@@ -102,7 +102,7 @@ func (ct Ciphertext) MarshalBinary() (p []byte, err error) {
 }
 
 // UnmarshalBinary decodes a slice of bytes generated by
-// MarshalBinary or WriteTo on the object.
+// [Ciphertext.MarshalBinary] or [Ciphertext.WriteTo] on the object.
 func (ct *Ciphertext) UnmarshalBinary(p []byte) (err error) {
 	_, err = ct.ReadFrom(buffer.NewBuffer(p))
 	return
@@ -111,7 +111,7 @@ func (ct *Ciphertext) UnmarshalBinary(p []byte) (err error) {
 // Plaintext stores an RGSW plaintext value.
 type Plaintext rlwe.GadgetPlaintext
 
-// NewPlaintext creates a new RGSW plaintext from value, which can be either uint64, int64 or *ring.Poly.
+// NewPlaintext creates a new RGSW plaintext from value, which can be either uint64, int64 or *[ring.Poly].
 // Plaintext is returned in the NTT and Montgomery domain.
 func NewPlaintext(params rlwe.Parameters, value interface{}, levelQ, levelP, BaseTwoDecomposition int) (*Plaintext, error) {
 	gct, err := rlwe.NewGadgetPlaintext(params, value, levelQ, levelP, BaseTwoDecomposition)

core/rgsw/encryptor.go

@@ -5,8 +5,8 @@ import (
 	"github.com/tuneinsight/lattigo/v5/ring/ringqp"
 )
 
-// Encryptor is a type for encrypting RGSW ciphertexts. It implements the rlwe.Encryptor
-// interface overriding the `Encrypt` and `EncryptZero` methods to accept rgsw.Ciphertext
+// Encryptor is a type for encrypting RGSW ciphertexts. It implements the [rlwe.Encryptor]
+// interface overriding the [rlwe.Encryptor.Encrypt] and [rlwe.Encryptor.EncryptZero] methods to accept [rgsw.Ciphertext]
 // types in addition to ciphertexts types in the rlwe package.
 type Encryptor struct {
 	*rlwe.Encryptor
@@ -19,7 +19,7 @@ func NewEncryptor(params rlwe.ParameterProvider, key rlwe.EncryptionKey) *Encryp
 	return &Encryptor{rlwe.NewEncryptor(params, key), params.GetRLWEParameters().RingQP().NewPoly()}
 }
 
-// Encrypt encrypts a plaintext pt into a ciphertext ct, which can be a rgsw.Ciphertext
+// Encrypt encrypts a plaintext pt into a ciphertext ct, which can be a [rgsw.Ciphertext]
 // or any of the `rlwe` cipheretxt types.
 func (enc Encryptor) Encrypt(pt *rlwe.Plaintext, ct interface{}) (err error) {
 
@@ -68,7 +68,7 @@ func (enc Encryptor) Encrypt(pt *rlwe.Plaintext, ct interface{}) (err error) {
 	return nil
 }
 
-// EncryptZero generates an encryption of zero into a ciphertext ct, which can be a rgsw.Ciphertext
+// EncryptZero generates an encryption of zero into a ciphertext ct, which can be a [rgsw.Ciphertext]
 // or any of the `rlwe` cipheretxt types.
 func (enc Encryptor) EncryptZero(ct interface{}) (err error) {
 
@@ -99,7 +99,7 @@ func (enc Encryptor) EncryptZero(ct interface{}) (err error) {
 	return nil
 }
 
-// ShallowCopy creates a shallow copy of this Encryptor in which all the read-only data-structures are
+// ShallowCopy creates a shallow copy of this [Encryptor] in which all the read-only data-structures are
 // shared with the receiver and the temporary buffers are reallocated. The receiver and the returned
 // Encryptors can be used concurrently.
 func (enc Encryptor) ShallowCopy() *Encryptor {

core/rgsw/evaluator.go

@@ -8,25 +8,25 @@ import (
 
 // Evaluator is a type for evaluating homomorphic operations involving RGSW ciphertexts.
 // It currently supports the external product between a RLWE and a RGSW ciphertext (see
-// Evaluator.ExternalProduct).
+// [Evaluator.ExternalProduct]).
 type Evaluator struct {
 	rlwe.Evaluator
 }
 
-// NewEvaluator creates a new Evaluator type supporting RGSW operations in addition
-// to rlwe.Evaluator operations.
+// NewEvaluator creates a new [Evaluator] type supporting RGSW operations in addition
+// to [rlwe.Evaluator] operations.
 func NewEvaluator(params rlwe.ParameterProvider, evk rlwe.EvaluationKeySet) *Evaluator {
 	return &Evaluator{*rlwe.NewEvaluator(params, evk)}
 }
 
-// ShallowCopy creates a shallow copy of this Evaluator in which all the read-only data-structures are
+// ShallowCopy creates a shallow copy of this [Evaluator] in which all the read-only data-structures are
 // shared with the receiver and the temporary buffers are reallocated. The receiver and the returned
 // Evaluators can be used concurrently.
 func (eval Evaluator) ShallowCopy() *Evaluator {
 	return &Evaluator{*eval.Evaluator.ShallowCopy()}
 }
 
-// WithKey creates a shallow copy of the receiver Evaluator for which the new EvaluationKey is evaluationKey
+// WithKey creates a shallow copy of the receiver [Evaluator] for which the evaluation key is set to the provided [rlwe.EvaluationKeySet]
 // and where the temporary buffers are shared. The receiver and the returned Evaluators cannot be used concurrently.
 func (eval Evaluator) WithKey(evk rlwe.EvaluationKeySet) *Evaluator {
 	return &Evaluator{*eval.Evaluator.WithKey(evk)}

core/rgsw/rgsw.go

@@ -1,3 +1,3 @@
 // Package rgsw implements an RLWE-based GSW encryption and external product RLWE x RGSW -> RLWE.
-// RSGW ciphertexts are tuples of two rlwe.GadgetCiphertext encrypting (`m(X)`, s*m(X)).
+// RSGW ciphertexts are tuples of two [rlwe.GadgetCiphertext] encrypting (`m(X)`, s*m(X)).
 package rgsw

core/rlwe/ciphertext.go

@@ -12,17 +12,17 @@ type Ciphertext struct {
 	Element[ring.Poly]
 }
 
-// NewCiphertext returns a new Ciphertext with zero values and an associated
+// NewCiphertext returns a new [Ciphertext] with zero values and an associated
 // MetaData set to the Parameters default value.
 func NewCiphertext(params ParameterProvider, degree int, level ...int) (ct *Ciphertext) {
 	op := *NewElement(params, degree, level...)
 	return &Ciphertext{op}
 }
 
-// NewCiphertextAtLevelFromPoly constructs a new Ciphertext at a specific level
+// NewCiphertextAtLevelFromPoly constructs a new [Ciphertext] at a specific level
 // where the message is set to the passed poly. No checks are performed on poly and
-// the returned Ciphertext will share its backing array of coefficients.
-// Returned Ciphertext's MetaData is allocated but empty	.
+// the returned [Ciphertext] will share its backing array of coefficients.
+// Returned [Ciphertext]'s MetaData is allocated but empty.
 func NewCiphertextAtLevelFromPoly(level int, poly []ring.Poly) (*Ciphertext, error) {
 
 	operand, err := NewElementAtLevelFromPoly(level, poly)
@@ -36,7 +36,7 @@ func NewCiphertextAtLevelFromPoly(level int, poly []ring.Poly) (*Ciphertext, err
 	return &Ciphertext{*operand}, nil
 }
 
-// NewCiphertextRandom generates a new uniformly distributed Ciphertext of degree, level.
+// NewCiphertextRandom generates a new uniformly distributed [Ciphertext] of degree, level.
 func NewCiphertextRandom(prng sampling.PRNG, params ParameterProvider, degree, level int) (ciphertext *Ciphertext) {
 	ciphertext = NewCiphertext(params, degree, level)
 	PopulateElementRandom(prng, params, ciphertext.El())

core/rlwe/decryptor.go

@@ -7,15 +7,15 @@ import (
 	"github.com/tuneinsight/lattigo/v5/utils"
 )
 
-// Decryptor is a structure used to decrypt Ciphertext. It stores the secret-key.
+// Decryptor is a structure used to decrypt [Ciphertext]. It stores the secret-key.
 type Decryptor struct {
 	params Parameters
 	ringQ  *ring.Ring
 	buff   ring.Poly
 	sk     *SecretKey
 }
 
-// NewDecryptor instantiates a new generic RLWE Decryptor.
+// NewDecryptor instantiates a new generic RLWE [Decryptor].
 func NewDecryptor(params ParameterProvider, sk *SecretKey) *Decryptor {
 
 	p := params.GetRLWEParameters()
@@ -32,22 +32,22 @@ func NewDecryptor(params ParameterProvider, sk *SecretKey) *Decryptor {
 	}
 }
 
-// GetRLWEParameters returns the underlying rlwe.Parameters.
+// GetRLWEParameters returns the underlying [Parameters].
 func (d Decryptor) GetRLWEParameters() *Parameters {
 	return &d.params
 }
 
-// DecryptNew decrypts the Ciphertext and returns the result in a new Plaintext.
-// Output pt MetaData will match the input ct MetaData.
+// DecryptNew decrypts the [Ciphertext] and returns the result in a new [Plaintext].
+// Output pt [MetaData] will match the input ct [MetaData].
 func (d Decryptor) DecryptNew(ct *Ciphertext) (pt *Plaintext) {
 	pt = NewPlaintext(d.params, ct.Level())
 	d.Decrypt(ct, pt)
 	return
 }
 
-// Decrypt decrypts the Ciphertext and writes the result in pt.
-// The level of the output Plaintext is min(ct.Level(), pt.Level())
-// Output pt MetaData will match the input ct MetaData.
+// Decrypt decrypts the [Ciphertext] and writes the result in pt.
+// The level of the output [Plaintext] is min(ct.Level(), pt.Level())
+// Output pt [MetaData] will match the input ct [MetaData].
 func (d Decryptor) Decrypt(ct *Ciphertext, pt *Plaintext) {
 
 	level := utils.Min(ct.Level(), pt.Level())
@@ -89,9 +89,9 @@ func (d Decryptor) Decrypt(ct *Ciphertext, pt *Plaintext) {
 	}
 }
 
-// ShallowCopy creates a shallow copy of Decryptor in which all the read-only data-structures are
+// ShallowCopy creates a shallow copy of [Decryptor] in which all the read-only data-structures are
 // shared with the receiver and the temporary buffers are reallocated. The receiver and the returned
-// Decryptor can be used concurrently.
+// [Decryptor] can be used concurrently.
 func (d Decryptor) ShallowCopy() *Decryptor {
 	return &Decryptor{
 		params: d.params,
@@ -101,9 +101,9 @@ func (d Decryptor) ShallowCopy() *Decryptor {
 	}
 }
 
-// WithKey creates a shallow copy of Decryptor with a new decryption key, in which all the
+// WithKey creates a shallow copy of [Decryptor] with a new decryption key, in which all the
 // read-only data-structures are shared with the receiver and the temporary buffers
-// are reallocated. The receiver and the returned Decryptor can be used concurrently.
+// are reallocated. The receiver and the returned [Decryptor] can be used concurrently.
 func (d Decryptor) WithKey(sk *SecretKey) *Decryptor {
 	return &Decryptor{
 		params: d.params,

core/rlwe/element.go

@@ -13,7 +13,7 @@ import (
 	"github.com/tuneinsight/lattigo/v5/utils/structs"
 )
 
-// ElementInterface is a common interface for Ciphertext and Plaintext types.
+// ElementInterface is a common interface for [Ciphertext] and [Plaintext] types.
 type ElementInterface[T ring.Poly | ringqp.Poly] interface {
 	El() *Element[T]
 	Degree() int
@@ -71,10 +71,10 @@ func NewElementExtended(params ParameterProvider, degree, levelQ, levelP int) *E
 	}
 }
 
-// NewElementAtLevelFromPoly constructs a new Element at a specific level
+// NewElementAtLevelFromPoly constructs a new [Element] at a specific level
 // where the message is set to the passed poly. No checks are performed on poly and
-// the returned Element will share its backing array of coefficients.
-// Returned Element's MetaData is nil.
+// the returned [Element] will share its backing array of coefficients.
+// Returned [Element]'s [MetaData] is nil.
 func NewElementAtLevelFromPoly(level int, poly []ring.Poly) (*Element[ring.Poly], error) {
 	Value := make([]ring.Poly, len(poly))
 	for i := range Value {
@@ -94,12 +94,12 @@ func (op Element[T]) Equal(other *Element[T]) bool {
 	return cmp.Equal(op.MetaData, other.MetaData) && cmp.Equal(op.Value, other.Value)
 }
 
-// Degree returns the degree of the target Element.
+// Degree returns the degree of the target element.
 func (op Element[T]) Degree() int {
 	return len(op.Value) - 1
 }
 
-// Level returns the level of the target Element.
+// Level returns the level of the target element.
 func (op Element[T]) Level() int {
 	return op.LevelQ()
 }
@@ -212,7 +212,7 @@ func GetSmallestLargest[T ring.Poly | ringqp.Poly](el0, el1 *Element[T]) (smalle
 	return el0, el1, true
 }
 
-// PopulateElementRandom creates a new rlwe.Element with random coefficients.
+// PopulateElementRandom creates a new [Element] with random coefficients.
 func PopulateElementRandom(prng sampling.PRNG, params ParameterProvider, ct *Element[ring.Poly]) {
 	sampler := ring.NewUniformSampler(prng, params.GetRLWEParameters().RingQ()).AtLevel(ct.Level())
 	for i := range ct.Value {
@@ -299,15 +299,15 @@ func (op Element[T]) BinarySize() (size int) {
 	return size + op.Value.BinarySize()
 }
 
-// WriteTo writes the object on an io.Writer. It implements the io.WriterTo
+// WriteTo writes the object on an [io.Writer]. It implements the [io.WriterTo]
 // interface, and will write exactly object.BinarySize() bytes on w.
 //
-// Unless w implements the buffer.Writer interface (see lattigo/utils/buffer/writer.go),
-// it will be wrapped into a bufio.Writer. Since this requires allocations, it
-// is preferable to pass a buffer.Writer directly:
+// Unless w implements the [buffer.Writer] interface (see lattigo/utils/buffer/writer.go),
+// it will be wrapped into a [bufio.Writer]. Since this requires allocations, it
+// is preferable to pass a [buffer.Writer] directly:
 //
-//   - When writing multiple times to a io.Writer, it is preferable to first wrap the
-//     io.Writer in a pre-allocated bufio.Writer.
+//   - When writing multiple times to a [io.Writer], it is preferable to first wrap the
+//     [io.Writer] in a pre-allocated [bufio.Writer].
 //   - When writing to a pre-allocated var b []byte, it is preferable to pass
 //     buffer.NewBuffer(b) as w (see lattigo/utils/buffer/buffer.go).
 func (op Element[T]) WriteTo(w io.Writer) (n int64, err error) {
@@ -348,15 +348,15 @@ func (op Element[T]) WriteTo(w io.Writer) (n int64, err error) {
 	}
 }
 
-// ReadFrom reads on the object from an io.Writer. It implements the
+// ReadFrom reads on the object from an [io.Writer]. It implements the
 // io.ReaderFrom interface.
 //
-// Unless r implements the buffer.Reader interface (see see lattigo/utils/buffer/reader.go),
-// it will be wrapped into a bufio.Reader. Since this requires allocation, it
+// Unless r implements the [buffer.Reader] interface (see see lattigo/utils/buffer/reader.go),
+// it will be wrapped into a [bufio.Reader]. Since this requires allocation, it
 // is preferable to pass a buffer.Reader directly:
 //
-//   - When reading multiple values from a io.Reader, it is preferable to first
-//     first wrap io.Reader in a pre-allocated bufio.Reader.
+//   - When reading multiple values from a [io.Reader], it is preferable to first
+//     first wrap [io.Reader] in a pre-allocated [bufio.Reader].
 //   - When reading from a var b []byte, it is preferable to pass a buffer.NewBuffer(b)
 //     as w (see lattigo/utils/buffer/buffer.go).
 func (op *Element[T]) ReadFrom(r io.Reader) (n int64, err error) {
@@ -408,7 +408,7 @@ func (op Element[T]) MarshalBinary() (data []byte, err error) {
 }
 
 // UnmarshalBinary decodes a slice of bytes generated by
-// MarshalBinary or WriteTo on the object.
+// [Element.MarshalBinary] or [Element.WriteTo] on the object.
 func (op *Element[T]) UnmarshalBinary(p []byte) (err error) {
 	_, err = op.ReadFrom(buffer.NewBuffer(p))
 	return