diff --git a/maroto.go b/maroto.go index e3e547f5..cbede33c 100644 --- a/maroto.go +++ b/maroto.go @@ -43,6 +43,9 @@ type maroto struct { pool async.Processor[[]core.Page, []byte] } +// New is responsible for create a new instance of core.Maroto. +// It's optional to provide an *entity.Config with customizations +// those customization are created by using the config.Builder. func New(cfgs ...*entity.Config) core.Maroto { cache := cache.New() cfg := getConfig(cfgs...) @@ -68,6 +71,11 @@ func New(cfgs ...*entity.Config) core.Maroto { return m } +// AddPages is responsible for add pages directly in the document. +// By adding a page directly, the current cursor will reset and the +// new page will appear as the next. If the page provided have +// more rows than the maximum useful area of a page, maroto will split +// that page in more than one. func (m *maroto) AddPages(pages ...core.Page) { for _, page := range pages { if m.currentHeight != m.headerHeight { @@ -78,16 +86,30 @@ func (m *maroto) AddPages(pages ...core.Page) { } } +// AddRows is responsible for add rows in the current document. +// By adding a row, if the row will extrapolate the useful area of a page, +// maroto will automatically add a new page. Maroto use the information of +// PageSize, PageMargin, FooterSize and HeaderSize to calculate the useful +// area of a page. func (m *maroto) AddRows(rows ...core.Row) { m.addRows(rows...) } +// AddRow is responsible for add one row in the current document. +// By adding a row, if the row will extrapolate the useful area of a page, +// maroto will automatically add a new page. Maroto use the information of +// PageSize, PageMargin, FooterSize and HeaderSize to calculate the useful +// area of a page. func (m *maroto) AddRow(rowHeight float64, cols ...core.Col) core.Row { r := row.New(rowHeight).Add(cols...) m.addRow(r) return r } +// RegisterHeader is responsible to define a set of rows as a header +// of the document. The header will appear in every new page of the document. +// The header cannot occupy an area greater than the useful area of the page, +// it this case the method will return an error. func (m *maroto) RegisterHeader(rows ...core.Row) error { height := m.getRowsHeight(rows...) if height+m.footerHeight > m.config.Dimensions.Height { @@ -104,6 +126,10 @@ func (m *maroto) RegisterHeader(rows ...core.Row) error { return nil } +// RegisterFooter is responsible to define a set of rows as a footer +// of the document. The footer will appear in every new page of the document. +// The footer cannot occupy an area greater than the useful area of the page, +// it this case the method will return an error. func (m *maroto) RegisterFooter(rows ...core.Row) error { height := m.getRowsHeight(rows...) if height > m.config.Dimensions.Height { @@ -115,6 +141,8 @@ func (m *maroto) RegisterFooter(rows ...core.Row) error { return nil } +// Generate is responsible to compute the component tree created by +// the usage of all other Maroto methods, and generate the PDF document. func (m *maroto) Generate() (core.Document, error) { m.provider.SetProtection(m.config.Protection) m.provider.SetCompression(m.config.Compression) @@ -130,6 +158,8 @@ func (m *maroto) Generate() (core.Document, error) { return m.generate() } +// GetStructure is responsible for return the component tree, this is useful +// on unit tests cases. func (m *maroto) GetStructure() *node.Node[core.Structure] { m.fillPageToAddNew() diff --git a/metricsdecorator.go b/metricsdecorator.go index 663c7961..b1900797 100644 --- a/metricsdecorator.go +++ b/metricsdecorator.go @@ -18,6 +18,8 @@ type metricsDecorator struct { inner core.Maroto } +// NewMetricsDecorator is responsible to create the metrics decorator +// for the maroto instance. func NewMetricsDecorator(inner core.Maroto) core.Maroto { return &metricsDecorator{ inner: inner, diff --git a/pkg/components/code/barcode.go b/pkg/components/code/barcode.go index 7ed7cc5c..4bf3ae41 100644 --- a/pkg/components/code/barcode.go +++ b/pkg/components/code/barcode.go @@ -16,6 +16,7 @@ type barcode struct { config *entity.Config } +// NewBar is responsible to create an instance of a Barcode. func NewBar(code string, ps ...props.Barcode) core.Component { prop := props.Barcode{} if len(ps) > 0 { @@ -29,11 +30,13 @@ func NewBar(code string, ps ...props.Barcode) core.Component { } } +// NewBarCol is responsible to create an instance of a Barcode wrapped in a Col. func NewBarCol(size int, code string, ps ...props.Barcode) core.Col { bar := NewBar(code, ps...) return col.New(size).Add(bar) } +// NewBarRow is responsible to create an instance of a Barcode wrapped in a Row. func NewBarRow(height float64, code string, ps ...props.Barcode) core.Row { bar := NewBar(code, ps...) c := col.New().Add(bar) diff --git a/pkg/components/code/matrixcode.go b/pkg/components/code/matrixcode.go index 695e074f..c54766fd 100644 --- a/pkg/components/code/matrixcode.go +++ b/pkg/components/code/matrixcode.go @@ -16,6 +16,7 @@ type matrixCode struct { config *entity.Config } +// NewMatrix is responsible to create an instance of a MatrixCode. func NewMatrix(code string, barcodeProps ...props.Rect) core.Component { prop := props.Rect{} if len(barcodeProps) > 0 { @@ -29,11 +30,13 @@ func NewMatrix(code string, barcodeProps ...props.Rect) core.Component { } } +// NewMatrixCol is responsible to create an instance of a MatrixCode wrapped in a Col. func NewMatrixCol(size int, code string, ps ...props.Rect) core.Col { matrixCode := NewMatrix(code, ps...) return col.New(size).Add(matrixCode) } +// NewMatrixRow is responsible to create an instance of a MatrixCode wrapped in a Row. func NewMatrixRow(height float64, code string, ps ...props.Rect) core.Row { matrixCode := NewMatrix(code, ps...) c := col.New().Add(matrixCode) diff --git a/pkg/components/code/qrcode.go b/pkg/components/code/qrcode.go index c51862e0..d704bcc8 100644 --- a/pkg/components/code/qrcode.go +++ b/pkg/components/code/qrcode.go @@ -16,6 +16,7 @@ type qrCode struct { config *entity.Config } +// NewQr is responsible to create an instance of a QrCode. func NewQr(code string, barcodeProps ...props.Rect) core.Component { prop := props.Rect{} if len(barcodeProps) > 0 { @@ -29,11 +30,13 @@ func NewQr(code string, barcodeProps ...props.Rect) core.Component { } } +// NewQrCol is responsible to create an instance of a QrCode wrapped in a Col. func NewQrCol(size int, code string, ps ...props.Rect) core.Col { qrCode := NewQr(code, ps...) return col.New(size).Add(qrCode) } +// NewQrRow is responsible to create an instance of a QrCode wrapped in a Row. func NewQrRow(height float64, code string, ps ...props.Rect) core.Row { qrCode := NewQr(code, ps...) c := col.New().Add(qrCode) diff --git a/pkg/components/col/col.go b/pkg/components/col/col.go index e308ce37..f71613d7 100644 --- a/pkg/components/col/col.go +++ b/pkg/components/col/col.go @@ -17,6 +17,7 @@ type col struct { style *props.Cell } +// New is responsible to create an instance of core.Col. func New(size ...int) core.Col { if len(size) == 0 { return &col{isMax: true} diff --git a/pkg/components/image/bytesimage.go b/pkg/components/image/bytesimage.go index 8c0d62ad..724c6828 100644 --- a/pkg/components/image/bytesimage.go +++ b/pkg/components/image/bytesimage.go @@ -18,6 +18,7 @@ type bytesImage struct { config *entity.Config } +// NewFromBytes is responsible to create an instance of an Image. func NewFromBytes(bytes []byte, extension extension.Type, ps ...props.Rect) core.Component { prop := props.Rect{} if len(ps) > 0 { @@ -32,11 +33,13 @@ func NewFromBytes(bytes []byte, extension extension.Type, ps ...props.Rect) core } } +// NewFromBytesCol is responsible to create an instance of an Image wrapped in a Col. func NewFromBytesCol(size int, bytes []byte, extension extension.Type, ps ...props.Rect) core.Col { image := NewFromBytes(bytes, extension, ps...) return col.New(size).Add(image) } +// NewFromBytesRow is responsible to create an instance of an Image wrapped in a Row. func NewFromBytesRow(height float64, bytes []byte, extension extension.Type, ps ...props.Rect) core.Row { image := NewFromBytes(bytes, extension, ps...) c := col.New().Add(image) diff --git a/pkg/components/image/fileimage.go b/pkg/components/image/fileimage.go index 0995c31f..6ee16221 100644 --- a/pkg/components/image/fileimage.go +++ b/pkg/components/image/fileimage.go @@ -16,6 +16,7 @@ type fileImage struct { config *entity.Config } +// NewFromFile is responsible to create an instance of an Image. func NewFromFile(path string, ps ...props.Rect) core.Component { prop := props.Rect{} if len(ps) > 0 { @@ -29,11 +30,13 @@ func NewFromFile(path string, ps ...props.Rect) core.Component { } } +// NewFromFileCol is responsible to create an instance of an Image wrapped in a Col. func NewFromFileCol(size int, path string, ps ...props.Rect) core.Col { image := NewFromFile(path, ps...) return col.New(size).Add(image) } +// NewFromFileRow is responsible to create an instance of an Image wrapped in a Row. func NewFromFileRow(height float64, path string, ps ...props.Rect) core.Row { image := NewFromFile(path, ps...) c := col.New().Add(image) diff --git a/pkg/components/line/line.go b/pkg/components/line/line.go index e26ea60d..0da27bef 100644 --- a/pkg/components/line/line.go +++ b/pkg/components/line/line.go @@ -14,6 +14,7 @@ type line struct { prop props.Line } +// New is responsible to create an instance of a Line. func New(ps ...props.Line) core.Component { lineProp := props.Line{} if len(ps) > 0 { @@ -26,11 +27,13 @@ func New(ps ...props.Line) core.Component { } } +// NewCol is responsible to create an instance of a Line wrapped in a Col. func NewCol(size int, ps ...props.Line) core.Col { r := New(ps...) return col.New(size).Add(r) } +// NewRow is responsible to create an instance of a Line wrapped in a Row. func NewRow(height float64, ps ...props.Line) core.Row { r := New(ps...) c := col.New().Add(r) diff --git a/pkg/components/list/list.go b/pkg/components/list/list.go index 55896675..fcf9a176 100644 --- a/pkg/components/list/list.go +++ b/pkg/components/list/list.go @@ -6,11 +6,17 @@ import ( "github.com/johnfercher/maroto/v2/pkg/core" ) +// Listable is the main abstraction of a listable item in a TableList. +// A collection of objects that implements this interface may be added +// in a list. type Listable interface { GetHeader() core.Row GetContent(i int) core.Row } +// BuildFromPointer is responsible to receive a collection of objects that implements +// Listable and build the rows of TableList. This method should be used in case of a collection +// of pointers. func BuildFromPointer[T Listable](arr []*T) ([]core.Row, error) { if len(arr) == 0 { return nil, errors.New("empty array") @@ -27,6 +33,9 @@ func BuildFromPointer[T Listable](arr []*T) ([]core.Row, error) { return Build(list) } +// Build is responsible to receive a collection of objects that implements +// Listable and build the rows of TableList. This method should be used in case of a collection +// of values. func Build[T Listable](arr []T) ([]core.Row, error) { if len(arr) == 0 { return nil, errors.New("empty array") diff --git a/pkg/components/page/page.go b/pkg/components/page/page.go index aa68ba6f..99563f3f 100644 --- a/pkg/components/page/page.go +++ b/pkg/components/page/page.go @@ -15,6 +15,7 @@ type page struct { prop props.Page } +// New is responsible to create a core.Page. func New(ps ...props.Page) core.Page { prop := props.Page{} if len(ps) > 0 { diff --git a/pkg/components/row/row.go b/pkg/components/row/row.go index 4045a62d..5550cc6b 100644 --- a/pkg/components/row/row.go +++ b/pkg/components/row/row.go @@ -16,6 +16,7 @@ type row struct { config *entity.Config } +// New is responsible to create a core.Row. func New(height float64) core.Row { return &row{ height: height, diff --git a/pkg/components/signature/signature.go b/pkg/components/signature/signature.go index b2328b8d..ae910afb 100644 --- a/pkg/components/signature/signature.go +++ b/pkg/components/signature/signature.go @@ -17,6 +17,7 @@ type signature struct { config *entity.Config } +// New is responsible to create an instance of a Signature. func New(value string, ps ...props.Signature) core.Component { prop := props.Signature{} if len(ps) > 0 { @@ -30,11 +31,13 @@ func New(value string, ps ...props.Signature) core.Component { } } +// NewCol is responsible to create an instance of a Signature wrapped in a Col. func NewCol(size int, value string, ps ...props.Signature) core.Col { signature := New(value, ps...) return col.New(size).Add(signature) } +// NewRow is responsible to create an instance of a Signature wrapped in a Row. func NewRow(height float64, value string, ps ...props.Signature) core.Row { signature := New(value, ps...) c := col.New().Add(signature) diff --git a/pkg/components/text/text.go b/pkg/components/text/text.go index 044f682d..f0bf2e9b 100644 --- a/pkg/components/text/text.go +++ b/pkg/components/text/text.go @@ -15,6 +15,7 @@ type text struct { config *entity.Config } +// New is responsible to create an instance of a Text. func New(value string, ps ...props.Text) core.Component { textProp := props.Text{} if len(ps) > 0 { @@ -27,11 +28,13 @@ func New(value string, ps ...props.Text) core.Component { } } +// NewCol is responsible to create an instance of a Text wrapped in a Col. func NewCol(size int, value string, ps ...props.Text) core.Col { text := New(value, ps...) return col.New(size).Add(text) } +// NewRow is responsible to create an instance of a Text wrapped in a Row. func NewRow(height float64, value string, ps ...props.Text) core.Row { r := New(value, ps...) c := col.New().Add(r) diff --git a/pkg/config/builder.go b/pkg/config/builder.go index 6a7ac589..91c4674c 100644 --- a/pkg/config/builder.go +++ b/pkg/config/builder.go @@ -18,6 +18,7 @@ import ( "github.com/johnfercher/maroto/v2/pkg/props" ) +// Builder is the abstraction responsible for global customizations on the document. type Builder interface { WithPageSize(size pagesize.Type) Builder WithDimensions(width float64, height float64) Builder @@ -59,6 +60,7 @@ type builder struct { backgroundImage *entity.Image } +// NewBuilder is responsible to create an instance of Builder. func NewBuilder() Builder { return &builder{ providerType: provider.Gofpdf,