captbaritone / captbaritone/grats

Support for `@` in descriptions

Open
#179 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
358
Forks
24
PR merge metrics
No merged PRs in 30d

Description

According to the docs, `@` in description comments makes the comment get truncated
> Depending upon your version of TypeScript, descriptions with a @ symbol in their text, for example a GitHub handle, may get truncated. To avoid this, you can wrap the tag in quotes or backticks.
>
> ```
> /** This comment was added by `@captbaritone`. */
> ```

This limitation makes it impossible to put GraphQL example code in documentation comments.

For example, take the native `@semanticNonNull` that grats ships with. This is impossible to declare using grats:

```typescript
import {Int} from 'grats';
/**
* Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
* In all other cases, the position is non-null.
*
* Tools doing code generation may use this information to generate the position as non-null if field errors are handled out of band:
*
* ```graphql
* type User {
* # email is semantically non-null and can be generated as non-null by error-handling clients.
* email: String @semanticNonNull
* }
* ```
*
* The `levels` argument indicates what levels are semantically non null in case of lists:
*
* ```graphql
* type User {
* # friends is semantically non null
* friends: [User] @semanticNonNull # same as @semanticNonNull(levels: [0])
*
* # every friends[k] is semantically non null
* friends: [User] @semanticNonNull(levels: [1])
*
* # friends as well as every friends[k] is semantically non null
* friends: [User] @semanticNonNull(levels: [0, 1])
* }
* ```
*
* `levels` are zero indexed.
* Passing a negative level or a level greater than the list dimension is an error.
* @gqlDirective on FIELD_DEFINITION
*/
export function semanticNonNull({ levels = [0] }: { levels: Int[] }) {}
```

Produces a truncated description:

"""
Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
In all other cases, the position is non-null.

Tools doing code generation may use this information to generate the position as non-null if field errors are handled out of band:

```graphql
type User {
# email is semantically non-null and can be generated as non-null by error-handling clients.
email: String
"""
directive @semanticNonNull(levels: [Int!]! = [0]) on FIELD_DEFINITION

Afaik there is currently no work around in grats to produce the desired output.

[Playground reproduction](https://grats.capt.dev/playground#N4IgJg9gxiBcIEsC2AHCAnALgAmASQDtMBfbAM3QiWwHIBzdAQ0wGcaBuAHQIHoAqPt2x9shMAijMApi2yYAFs2yNsaFgkwIIBbAlkspSRkQmMANmYCe2AtpsBXC7F0492bVYcXdZOfKnoUrqyKkaYUPIIBHTYAZToujoKQQAGcRgsKcroTJYAdEIihMreEMkJkgYsADR+QWoaWjputgQAtASOZgU6gr3YACoQEGaykFExUBBgQXRSBAHMTdhG1vYGfm5RZBhhy5gQ2HMLTJhByaoQ6pp2jLKtHV0+5AhSZmCxORnZQYoEYGYpB8IPYcBBfAAjYxgWCFQrYFKIhiMFDyACOZnhmEsKCCAFUDAlgPDsKTsABiWJGBBmYLYAxGEySCzWB6dbzQ7CSHQQ2bzRZnD53GzaR7eCHWdLoNp-AETLlmV5EFg9YRk0mGRg05wAZUw6HlAAEGcZNFAAHLac1deHEeGIlJw-oDfwIwEANzemWydHsSHmrn+pjOsgA7oocB6vT96ZqmeZPK0vLSoly7kFwdhFSxWLDevakUxURisTj8YTcCSyZSKEqwLI3Cb4yyRTp2Zj+ura-N684ANoEgIAXWwxrjZstBGt3kpLEY-uUsjHjInVq6AAoo6N+wAGIcASidavVlKknvQ1m7-xYfYA1iPG+PTC2k+2q6Sr73sAPCSPl6aJEnaczE3M8vX7ABGA8jxEE9yANHsQjDN5aWFMCL3gusb3vOkmzNBNWTsN9OzJT8WH7Qd0D-PDALXCxQM9bdvx3WooMPfo7X6B0YLdMDRiyRhAmwAAvAJDiiGYAA8gVVEQAAU7nUaJlBsKQ6CWT0sz49wEhULcjkCaQEgUYw6izPQcHEf0CHUOw3FMqVZNHOgMQAEQQQIoE0TS7AAMTwABRAAZVyAH1XIC-zzTwAY8AAeXNQoeG4KRJLQLByHsAgvOWGiLTokDgC0xjZAAXmYkdiGcIqt3I0QiD7Sr91wYgQGqEApgIMgEDoOBQHbRgIUBAAhSxXKkMhGEcTA4H1ewpHawJ0swAYyx1KADRQFaywCr50BYWb0Hm4h2vdV5Qz6kAQUwFBQTiramjgEAWABNrnvkCBQwAcVOFh3M87yZDgSbRikE6QAANQCgAlHV4vNOAIOIIA).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.