Skip to content

SymbolInfo restructure: one structured Documentation accessor, no raw docblock string #542

Description

@Firehed

SymbolInfoInterface carries structured documentation. The raw docblock string field is removed.

Blocked by #541 (docblock parser utility) and #538 (one symbol interface).

Unblocks #520 (DocblockTypeSource reads the parsed docblock off SymbolInfoInterface).

Motivation

Today ClassInfo, MethodInfo, PropertyInfo, ConstantInfo, and EnumCaseInfo each carry a ?string $docblock field. getDocumentation() returns text derived from it by DocblockParser::extractDescription. Any docblock-typing work would naturally reach for the same string, at which point "what does the docblock say for this symbol" has two consumers of the raw text, and the source-specific parsing rules leak into every caller.

If SymbolInfoInterface carries a structured Documentation populated once at construction time, the raw string never crosses the interface and consumers ask for the fact they want by name.

Shape

  • One accessor on SymbolInfoInterface: getDocumentation(): Documentation. No separate parsed-docblock accessor.
  • Documentation is one value type carrying the description, the deprecation flag and message, and the parsed docblock subtree from Adopt external docblock parser behind ParsedDocblock utility #541. Everyone reads from it.
  • Each SymbolInfoInterface producer reads the docblock text in the way natural to its source and calls DocblockParser::parse(text, NameContext). A reflected symbol's NameContext carries its declaring namespace only, no import table; record that where the producer builds it.
  • The raw string field is removed from every implementation.
  • HasSymbolLocationTrait's DocblockParser::extractDescription call goes; ResolvedSymbolPresenter reads the structured value.
  • ExpressionResolver's @var element-type inference reads the parsed docblock through Documentation.

Rule edits this needs

The disallowedMethodCalls entry for DocblockParser::extractDescription is removed with the method. Any allowlist path or ledger row that named DocblockParser, HasSymbolLocationTrait, or ResolvedSymbolPresenter as a docblock-string reader is updated. The human makes these edits.

Done

  • No $docblock string field on any Domain\*Info class.
  • SymbolInfoInterface::getDocumentation() returns Documentation.
  • Every producer populates it at construction.
  • No caller reads a raw docblock string outside Domain\Docblock\DocblockParser.
  • Hover, completion detail, and signature help output is byte-for-byte unchanged (parity goldens green).
  • composer test green.

Issue body drafted by AI.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    MxNDifferent behavior/resolution for the same thing in different contextsai-authoredquestionFurther information is requested

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions