docs(api): refine public API docs + test title cleanup

[olih]

This PR refines developer‑focused documentation across the public API and tidies test titles for coherence.

Summary

• Public API docs: clearer guidance and practical tips

  • evaluation_context: prefix contract, boolean/list helpers, lifecycle tips
  • function_factory: extension guidance, registry usage, comparators
  • fuzzy_boolean: certainty semantics (AND/OR/NOT) and compact storage
  • parser_options: configuration guidance, validator best practices, case sensitivity
  • supported_prefixes: design tips (avoid overlaps) and perf notes
  • token: invariants, TokenTypes reference, hasError intent
  • tokeniser: comments/keywords, unparse purpose/limits, char classes
  • semantic_exception: deterministic, actionable messages with token context
  • boolean_expression_analyser: grammar, precedence/associativity, extension points
  • semantic_analyser: responsibilities, rule spans, comment handling
  • boolean_interpreter: evaluation order, ruleState writeback

• Tests: rename a few unclear titles and trim comments

  • boolean_interpreter_test: clearer intent
  • boolean_expression_analyser_test: precise parser behavior in titles
  • token_stream_test: simplified comments
  • tokeniser_test: minimized stub docs

Validation

• Ran npx baldrick-broth@latest test unit: formatting, coverage, example run, and unit tests all passed.

Notes

• No behavior changes; documentation only + test title/comment cleanup.
• Line endings remain LF; no config changes to git attributes.