microsoft / microsoft/TypeScript
Documentation: Clarify declaration files and the declare keyword
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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