Mark Statement::execute() and the fetch family [[nodiscard]] (#59)

[mariuz]

Follow-up to #59, as offered there.

What

• Statement::execute() and the cursor-movement family (fetchNext/fetchPrior/fetchFirst/fetchLast/fetchAbsolute/fetchRelative) are now [[nodiscard]], each with a C++20 reason message, so the silent first-row-loss shape

  stmt.execute(transaction);
  while (stmt.fetchNext())  // starts at row TWO

  becomes a compiler warning at the call site. The doxygen comments gain the missing @return lines and a note on the execute-fetches-first-row semantics.

• The tests' intentional discards (DDL/DML executes, reads of a known-existing row, re-execution checks) are annotated with explicit (void) casts — 49 sites, found mechanically by compiling with the new header and fixing every warning, so the suite stays warning-free under -Wall//W4.

• The README example gains a short note explaining why the loop is if (execute()) do … while (fetchNext()); and what the (void) idiom is for.

Why

While writing 43 small fb-cpp programs (hands-on companions to a Firebird architecture paper), three of them independently wrote the execute(); while (fetchNext()) shape and silently lost the first row — no error, just missing data. Details and field report in #59.

Verification

• Every library and test translation unit compiles warning-free with the new attributes (g++ 13, -std=c++20 -Wall, Linux aarch64).
• All changed files pass clang-format 20.1.8 (the version check-format.sh uses) byte-for-byte.
• I could not link/run the Boost.Test suite locally (no vcpkg toolchain on this machine) — relying on CI for the run; the changes to test files are (void) casts only.

🤖 Generated with Claude Code

[asfernandes]

As you see, this is not needed for DDL and I do not want that (void) thing everywhere.