graphqlite
graphqlite copied to clipboard
Add `description` attribute to annotations to override PHPDoc
Currently, the PHPDoc comment is exposed over the schema as the description. This is fine to remain. However, often there are times where internals are needed in the PHPDoc. In fact, I'd argue that the PHPDoc should really be reserved for internal documentation only. It's too easy to accidentally expose something undesired in the PHPDoc. Additionally, there isn't any way to add additional internal documentation in the PHPDoc without having it also added to the GraphQL schema.
Therefore, with the addition of a new param description
on annotations, we can override whatever description is in the PHPDoc. This would maintain BC and simplicity for others, but provide a finer grained option for other cases.
It's worth mentioning that a description
attribute is currently supported by some annotations. It's needed on the following:
-
Query
-
Mutation
-
Type
-
ExtendType
-
Factory
I'd consider implementing a DescriptionFieldMiddleware using the existing FieldMiddlewares as described in https://github.com/thecodingmachine/graphqlite/issues/439#issuecomment-1031227899 by @withinboredom since it would be possible to have the new Annotation not ever trying to read PHPDoc and the current system side by side and deprecate the description attribute on all other Annotations for a later release.