docs: improve godoc and documentation [skip ci]

pkg/modules/api/doc.go

@@ -1,3 +1,3 @@
-// Package api provides a module, which is an HTTP server. Other modules may
-// add multipart/form-data routes, middlewares, and health checks.
+// Package api implements the HTTP server module. Other modules register
+// multipart/form data routes, middlewares, and health checks through it.
 package api

pkg/modules/chromium/doc.go

@@ -1,4 +1,3 @@
-// Package chromium provides a module which adds routes for converting HTML
-// documents to PDF. Other modules may also retrieve the [Api] provided by this
-// module.
+// Package chromium adds routes for converting HTML documents to PDF. Exposes
+// an [Api] for other modules.
 package chromium

pkg/modules/exiftool/doc.go

@@ -1,11 +1,6 @@
-// Package exiftool provides an implementation of the gotenberg.PdfEngine
-// interface using the ExifTool command-line tool. This package allows for:
+// Package exiftool implements gotenberg.PdfEngine using the ExifTool command-line tool. Reads and writes PDF metadata.
 //
-// 1. The reading of metadata.
-// 2. The writing of metadata.
+// Requires the EXIFTOOL_BIN_PATH environment variable.
 //
-// The path to the exiftool binary must be specified using the
-// EXIFTOOL_BIN_PATH environment variable.
-//
-// See: https://exiftool.org.
+// See https://exiftool.org.
 package exiftool

pkg/modules/libreoffice/api/doc.go

@@ -1,3 +1,2 @@
-// Package api provides a module which manages a LibreOffice instance and
-// interacts with it via the UNO (Universal Network Objects) API.
+// Package api manages a LibreOffice instance via the UNO API.
 package api

pkg/modules/libreoffice/doc.go

@@ -1,3 +1,3 @@
-// Package libreoffice provides a module which adds a route for converting
-// documents to PDF with LibreOffice.
+// Package libreoffice adds a route for converting documents to PDF with
+// LibreOffice.
 package libreoffice

pkg/modules/libreoffice/pdfengine/doc.go

@@ -1,6 +1,3 @@
-// Package pdfengine provides a module which interacts with LibreOffice via the
-// UNO (Universal Network Objects) API and implements the gotenberg.PdfEngine
-// interface. This package allows for:
-//
-// 1. The conversion to specific PDF formats.
+// Package pdfengine implements gotenberg.PdfEngine using LibreOffice via the
+// UNO API. Converts PDFs to specific PDF formats.
 package pdfengine

pkg/modules/pdfcpu/doc.go

@@ -1,8 +1,5 @@
-// Package pdfcpu provides an implementation of the gotenberg.PdfEngine
-// interface using the pdfcpu command-line tool. This package allows for:
+// Package pdfcpu implements gotenberg.PdfEngine using the pdfcpu command-line
+// tool. Merges and splits PDF files.
 //
-// 1. The merging of PDF files.
-// 2. The splitting of PDF files.
-//
-// See: https://github.com/pdfcpu/pdfcpu.
+// See https://github.com/pdfcpu/pdfcpu.
 package pdfcpu

pkg/modules/pdfengines/README.md

@@ -1,14 +1,32 @@
 # Adding PDF Engine Features
 
-When adding a new PDF engine capability (e.g., bookmarks, watermark, stamp, embed), you must update the Makefile to include the corresponding engine list variable and flag. Every `--pdfengines-*-engines` flag registered in `pkg/modules/pdfengines/pdfengines.go` must have a matching entry in the Makefile:
+Each new PDF engine capability (e.g., bookmarks, watermark, stamp, embed) requires a matching Makefile entry. The Makefile variables control which engines are passed to Gotenberg at `make run` and `make test-integration` time (via `compose.yaml`). If you skip this step, the flag still works when set manually, but `make run` falls back to the default defined in `pdfengines.go`, which may not include the new engine.
 
-1. **Add a variable** in the Makefile's variable block (around line 60-70):
+Every `--pdfengines-*-engines` flag registered in `pkg/modules/pdfengines/pdfengines.go` must have a corresponding variable and flag in the Makefile:
+
+1. **Add a variable** in the Makefile's variable block (around line 60 to 70):
    ```makefile
    PDFENGINES_<FEATURE>_ENGINES=<default engines>
    ```
-2. **Add the flag** in the Makefile's command args block (around line 140-155):
-   ```makefile
-   --pdfengines-<feature>-engines=$(PDFENGINES_<FEATURE>_ENGINES) \
+2. **Add the flag** in `compose.yaml`'s command args:
+   ```yaml
+   - "--pdfengines-<feature>-engines=${PDFENGINES_<FEATURE>_ENGINES}"
    ```
 
-The default value should match what is defined in `pdfengines.go`'s `fs.StringSlice(...)` call for that flag.
+The default value must match the `fs.StringSlice(...)` call for that flag in `pdfengines.go`.
+
+## Example: Rotate
+
+The rotate feature was added with two engines (`pdfcpu` and `pdftk`). Here is what the additions look like:
+
+**Makefile** (variable block):
+
+```makefile
+PDFENGINES_ROTATE_ENGINES=pdfcpu,pdftk
+```
+
+**compose.yaml** (command args):
+
+```yaml
+- "--pdfengines-rotate-engines=${PDFENGINES_ROTATE_ENGINES}"
+```

pkg/modules/pdfengines/doc.go

@@ -1,3 +1,3 @@
-// Package pdfengines a way to gather and manage multiple modules that
-// implement the gotenberg.PdfEngine interface.
+// Package pdfengines gathers and manages modules that implement
+// gotenberg.PdfEngine.
 package pdfengines

pkg/modules/pdftk/doc.go

@@ -1,11 +1,7 @@
-// Package pdftk provides an implementation of the gotenberg.PdfEngine
-// interface using the PDFtk command-line tool. This package allows for:
+// Package pdftk implements gotenberg.PdfEngine using the PDFtk command-line
+// tool. Merges and splits PDF files.
 //
-// 1. The merging of PDF files.
-// 2. The splitting of PDF files.
+// Requires the PDFTK_BIN_PATH environment variable.
 //
-// The path to the PDFtk binary must be specified using the PDFTK_BIN_PATH
-// environment variable.
-//
-// See: https://gitlab.com/pdftk-java/pdftk.
+// See https://gitlab.com/pdftk-java/pdftk.
 package pdftk

pkg/modules/prometheus/doc.go

@@ -1,5 +1,4 @@
-// Package prometheus provides a module which collects metrics and exposes them
-// via an HTTP route.
+// Package prometheus collects metrics and exposes them via an HTTP route.
 //
-// See: https://prometheus.io/.
+// See https://prometheus.io/.
 package prometheus

pkg/modules/qpdf/doc.go

@@ -1,12 +1,7 @@
-// Package qpdf provides an implementation of the gotenberg.PdfEngine
-// interface using the QPDF command-line tool. This package allows for:
+// Package qpdf implements gotenberg.PdfEngine using the QPDF command-line
+// tool. Merges, splits, and flattens PDF files.
 //
-// 1. The merging of PDF files.
-// 2. The splitting of PDF files.
-// 3. Flattening of PDF files
+// Requires the QPDF_BIN_PATH environment variable.
 //
-// The path to the QPDF binary must be specified using the QPDK_BIN_PATH
-// environment variable.
-//
-// See: https://github.com/qpdf/qpdf.
+// See https://github.com/qpdf/qpdf.
 package qpdf

pkg/modules/webhook/doc.go

@@ -1,3 +1,3 @@
-// Package webhook provides a module which adds a middleware for uploading
-// output files to any destination in an asynchronous fashion.
+// Package webhook adds middleware for uploading output files to any destination
+// asynchronously.
 package webhook