microsoft / microsoft/typespec

[Bug]: Confusing and wrong documentation on `is` vs `extend`

Open
#8,541 0 comments 0 reactions 0 assignees View on GitHub
bug docs mq triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Describe the bug

I think the current documentation is very confusing and even a little wrong on is operator.

https://typespec.io/docs/language-basics/models/#using-the-is-operator

Usage of `is` instead of `extends` can't be recommended, just because is wouldn't allow you to specify new properties which are not of the base type, while extends allows.
> In many languages, this would probably result in the same emitted code as is and it is recommended to use is Record instead.

It is missing additional context of that is is transfering decorators, while extends not.

Implementing own emitter this resulted in a confusion of properties completely stripped out by compiler without any errors when used `is` instead of `extends`.

Therefore I'd suggest remove at least is usage recommendation over extends at least. But generally to improve documentation, as it's been already more than a year since TypeSpec rename and half a year since release and documentation didn't improve match.

### Reproduction

-

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] Check that this is a concrete bug. For Q&A open a [GitHub Discussion](https://github.com/Microsoft/typespec/discussions).
- [x] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

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.