microsoft / microsoft/TypeScript

Documentation: Clarify declaration files and the declare keyword

Open
#23,262 2 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Docs
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

TypeScript Version: 2.8.0

Search Terms:
document declaration files

** Issue**
It doesn't look like you actually define what a declaration file is in your documentation. For instance, your introduction to these at https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html tells me you're going to help me learn how to write them, but not what they are or why I'd want one. But, I don't think this makes it easy for a newbie to understand.

Similarly, you don't seem to explain when the declare keyword is, or when it should be used (as far as I can tell, it is used when you need to tell the compiler that the module/library/whatever has a value of some type).

You also seem to make some references to the global namespace (declare global { ... })), but don't seem to directly explain it anywhere.

Code
n/a

Expected behavior:
n/a

Actual behavior:
n/a

Playground Link:
n/a

Related Issues:
n/a

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

Start with the declaration-files introduction at https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html, then trace its references to declare global and related declaration-file guidance. Review the surrounding handbook material before editing. Done means the documentation clearly defines declaration files, explains why and when to use declare, and directly explains the global namespace.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.