Skip to content

Removed DocBlock descriptions is a DX regression #723

@alexchexes

Description

@alexchexes

In v3.4.0 you removed DocBlock descriptions from generated functions (PR #707). I understand the goal (smaller package), but this is a noticeable usability regression in modern IDEs.

  • People don't want to google PHP manual just to remind themselves what the behavior is depending on the passed argument types, or what preg_match returns (is it 1 or true?).
  • Types alone are not enough. For many "rare" or non-obvious functions, the argument meaning (formats, flags, special values, side effects) is essential and only conveyed via descriptions.
  • This also creates a bad compromise: built-in PHP functions still have rich hover docs (via stubs/Intelephense/PhpStorm), while Safe functions now don't. So adopting Safe becomes "exceptions instead of false" at the cost of losing IDE docs. If Safe had never had them, that would be one thing. But now it does not feel like a very reasonable trade just to save ~1MB compressed.

Please consider either:

  1. restoring descriptions
  2. providing an opt-in choice whether we use package with them or without.

Thanks - Safe is great, while newer software becoming less convenient than older is not.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions