When describing the HTTP Cache "Expiration" model (at least at https://symfony.com/doc/current/http_cache.html#expiration-caching, https://symfony.com/doc/current/http_cache/expiration.html#expiration-with-the-cache-control-header) we always use s-maxage/setSharedMaxAge(), making it look like a convenient shortcut for public, maxage=..., and suggesting that s-maxage would just provide another maxage value for the shared cache.

In fact, s-maxage has an additional implication: It prevents re-using a response in a stale-if-error scenario (see symfony/symfony#35305).

Here's the relevant parts of the spec.

RFC 7234 Section 5.2.2.9

The "s-maxage" response directive indicates that, in shared caches,
the maximum age specified by this directive overrides the maximum age
specified by either the max-age directive or the Expires header
field. The s-maxage directive also implies the semantics of the
proxy-revalidate response directive.

... where proxy-revalidate in turn implies must-revalidate which says ...

The "must-revalidate" response directive indicates that once it has
become stale, a cache MUST NOT use the response to satisfy subsequent
requests without successful validation on the origin server.

Also, Section 4.2.4 summarizes this as

A cache MUST NOT generate a stale response if it is prohibited by an
explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
cache directive, a "must-revalidate" cache-response-directive, or an
applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
see Section 5.2.2).

My suggestion is to update the documentation to always show the combination of public and maxage (which gives shared expiration caching plus stale-if-error behavior) instead of s-maxage examples.

I can try to make the actual PR, although I am really slow when trying to mangle .rst. But in general – do you understand the specs the same way and is that change a good idea?