microsoft / microsoft/tsdoc

TSDoc tag for tagged template literal declaring a language syntax it accepts?

Open
#284 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
5k
Forks
162
Avg merge
17h 24m
Merged PRs (30d)
8

Description

It's become somewhat common for tagged literals to be used to embed markup or other languages within a string, for instance a wide variety of CSS-in-JS solutions. By default, these are not syntax highlighted, linted, type checked etc in most tooling. There are some tooling extensions that are either syntax-specific (like this one for Sass) or fussy to use (like this one which must be repetitively used at a tagged literal call site and looks quite odd in that position).

It would be nice to be able to add a TSDoc tag to indicate that a template literal accepts a given language syntax. This would allow tooling to automatically/opt-in inject/perform functionality associated with that nested syntax. A contrived example:

/**
 * Renders EsotericMarkupLang to CompileTargetLang.
 *
 * @syntax esoteric
 */
const esoteric = (
  strings:     TemplateStringsArray,
  expressions: readonly any[]
) => {
  // ...
};

esoteric`
  #️⃣  This is an EsotericMarkupLang block

  My tooling knows about me!

  #️⃣#️⃣  For some reason...

  ... in EsotericMarkupLang, headings are declared with emoji 🤷
`

Contributor guide

No contributing guide indexed for this repository

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

Start with the issue's tagged-template example and its motivation around syntax highlighting, linting, and type checking. Review the linked Sass and comment-tagged-template tooling references to understand the proposed use cases. Done would require a resolved specification direction for whether and how a TSDoc tag such as @syntax should be defined.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.