per_platform help text shows plugin-focused guide, not usage

[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 Add reference docs for BUILD file symbols pantsbuild.org#216
• Relevant issues:
  • BUILD file symbols #18117
  • Modernizing objects and context_aware_object_factories (including so it shows up in docsite) #14832