docs: document global job priority behavior

[vibhor-aggr]

Summary

Document that job assignment priority is global across registered functions/queues after the recent priority-selection change.

This updates the protocol reference and the user-facing CLI, HTTP, and libgearman priority documentation so readers do not infer that priority is only applied within each function.

Fixes #465.

Verification

• git diff --check
• Inspected current gearman_server_job_take() implementation and priority regression coverage

Note: I could not run a Sphinx documentation build in this environment because the local Python environment does not have the sphinx module installed.

[esabol]

Looks good to me! Thank you!

@p-alik or @SpamapS : Do you want to review these changes?

[p-alik]

Review

Overview

Docs-only PR (9 files, +38/-3) documenting a behavior change from a prior fix (#465): job priority selection is global across all registered functions/queues, not scoped per-function. Updates PROTOCOL, the gearman CLI manpage, gearmand.rst (HTTP), and several libgearman task/priority pages with a consistent clarifying sentence.

Correctness check

Verified the claim against the actual implementation in libgearman-server/gearmand_con.cc:360 (gearman_server_job_take): the outer loop iterates priority (HIGH → MAX), and only the inner loop iterates workers/functions — meaning higher-priority jobs across all functions are drained before lower-priority jobs from any function. This matches the doc's claim exactly. ✅

Also checked libgearman-server/text.cc:122 for prioritystatus — counts are indeed collected per function, consistent with the new PROTOCOL note that counts are per-function while selection is still global. ✅

Code quality / style

• Wording is consistent (near-identical sentence reused across libgearman pages), appropriate for docs meant to be read standalone per-function-reference page.
• Minor RST hygiene fixes bundled in (removing two stray trailing blank lines in gearman_client_add_task_background.rst and gearman_client_do_background.rst) — harmless, slightly out of scope but trivial.
• Manually traced the RST structure around the gearmand.rst insertion (new paragraph placed between an indented bullet block and a pre-existing whitespace-only line): a blank line is correctly inserted before the new paragraph, so the literal block terminates properly before the new unindented paragraph starts. No structural break found.

Potential issues

• Unverifiable build: the author notes Sphinx wasn't available to confirm the doc build; same limitation here (no docutils/sphinx in this review environment). Worth a maintainer running make docs (or equivalent) before merge given 6+ files with new paragraph insertions.
• Redundancy vs. single source of truth: the same explanatory sentence is duplicated verbatim across 6 files. Future updates to this behavior will require touching all 6 in lockstep — a shared .. include:: snippet or a single canonical page + cross-reference could reduce drift risk. Not a blocker for a doc clarification PR, just a maintainability note.
• No test coverage needed — this is purely documentation, no code paths changed.

Security

No security implications; text-only changes.

Verdict

Straightforward, accurate documentation fix that closes a real gap (#465) and matches the current implementation. No functional or correctness issues found.