MichalLytek / MichalLytek/type-graphql

Feature: Remove indentation from description fields

Open
#250 4 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Community :family_man_girl: Discussion :speech_balloon: Enhancement :new:
Dominant language
TypeScript
Stars
8.1k
Forks
672
PR merge metrics
No merged PRs in 30d

Description

The description option available on most (all?) decorators is a fantastic tool for adding documentation in a way that plays nicely with the rest of the GraphQL tooling ecosystem.

A minor frustration with this feature is the fact that some of these other tools render the description as Markdown (a perfectly reasonable feature for those tools). However, given how most people likely write out longer descriptions in their Typescript source, the result that a regular description is treated like a code block:

```ts
class Foo {

@Field({ description: `
Some long
multiline description
or perhaps haiku?
`})
bar: string;

// Results in description = "\n Some long\n multiline description ...
```

Because of the source code indentation, the multi-line string has four spaces before each line, which markdown treats as a code block, and renders with whitespace: nowrap, resulting in this:

![image](https://user-images.githubusercontent.com/707213/52359340-f3c55400-29f6-11e9-92f6-983bce9ba3ff.png)

_from GraphQL Voyager_

**Describe the solution you'd like**
The description value passed to each decorator should have any base level indentation removed (i.e. indentation present on every line - purposeful indentation should be preserved).

**Describe alternatives you've considered**
Don't do anything and leave this up to the user. That's my current solution, and it's certainly working. It's just a minor annoyance to remember to wrap every description field with some kind of `stripIndentation` call.

Or, ask tools like GraphQL Voyager to either:

* Don't render as Markdown. This is a non-started, since it's undoubtedly a useful feature
* Render as Markdown, but they do the indentation stripping. That could work, but it feels like it's _slightly_ more the responsibility of whatever is generating the description fields to generate accurate values.

**Additional context**
Happy to PR this, but didn't want to jump the gun if you'd rather leave it userland.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue does not name files or tests; start by locating how decorator description values are handled in the TypeScript source. Check existing tests around descriptions, then verify that shared base indentation is removed while purposeful indentation remains, including multiline Markdown descriptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
graphql, typescript
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.