#20980 `per_platform` help text shows plugin-focused guide, not usage Issue created by huonw Describe the bug The

per_platform

doc string appears in the output of

pants help per_platform

, but that doc string is currently entirely focused on plugin authors using I think it'd be more helpful for the

help

output to be focused on how to use it:

PANTS_VERSION=2.22.0.dev3 pants help per_platform

`
`per_platform` BUILD file symbol
--------------------------------

Signature: per_platform(linux_arm64: '_T | None' = None, linux_x86_64: '_T | None' = None, macos_arm64: '_T | None' = None, macos_x86_64: '_T | None' = None) -> None

An object containing differing homogeneous platform-dependent values.

The values should be evaluated for the execution environment, and not the host environment
(I.e. it should be evaluated in a `rule` which requests `Platform`).

Expected usage is roughly:

```python
class MyFieldType(...):
    value = str | per_platform[str]

    @classmethod
    def compute_value(  # type: ignore[override]
        cls,
        raw_value: Optional[Union[str, per_platform[str]]],
        address: Address,
    ) -> Optional[Union[str, per_platform[str]]]:
        if isinstance(raw_value, per_platform):
            # NOTE: Ensure the values are homogeneous
            raw_value.check_types(str)

        return raw_value

...

@rule
async def my_rule(..., platform: Platform) -> ...:
    field_value = target[MyFieldType].value

    if isinstance(field_value, per_platform):
        field_value = field_value.get_value_for_platform(platform)

    ...

NOTE: Support for this object should be heavily weighed, as it would be inappropriate to use in certain contexts (such as the

source

field in a

foo_source

target, where the intent is to support differing source files based on platform. The result would be that dependency inference (and therefore the dependencies field) wouldn't be knowable on the host, which is not something the engine can support yet). ```` Bonus points: while writing this, write some docs for

http_source

too:

PANTS_VERSION=2.22.0.dev3 pants help http_source

doesn't show anything. Pants version 2.22.0.dev3 OS both Additional info • Will appear in online docs too after pantsbuild/pantsbuild.org#216 • Relevant issues: • #18117 • #14832 pantsbuild/pants