microsoft / microsoft/vscode

Outdated JSDoc on TextEditor.viewColumn ("when the editor column is larger than three")

Open
#335,331 1 comment 0 reactions 1 assignee Claimed by @justschen View on GitHub
stale triage-needed
Dominant language
TypeScript
Stars
193k
Forks
42.4k
PR merge metrics
PR metrics pending

Description

Does this issue occur when all extensions are disabled?: Yes

- VS Code Version: 1.136.2 (and latest main)
- OS Version: Windows

Steps to Reproduce:

1. Inspect [`src/vscode-dts/vscode.d.ts`](https://github.com/microsoft/vscode/blob/main/src/vscode-dts/vscode.d.ts#L1286-L1291) at lines 1286–1291.
2. The JSDoc for `TextEditor.viewColumn` states:
```typescript
/**
* The column in which this editor shows. Will be `undefined` in case this
* isn't one of the main editors, e.g. an embedded editor, or when the editor
* column is larger than three.
*/
readonly viewColumn: ViewColumn | undefined;
```

---

### Why this is outdated:

1. **What the comment claims:** An editor column > 3 returns `undefined`.
2. **What the code actually does today:**
In [`extHostTypeConverters.ts`](https://github.com/microsoft/vscode/blob/main/src/vs/workbench/api/common/extHostTypeConverters.ts#L349-L355), `ViewColumn.to(position)` returns `position + 1` for any valid editor group column (`>= 0`):
```typescript
export function to(position: EditorGroupColumn): vscode.ViewColumn {
if (typeof position === 'number' && position >= 0) {
return position + 1; // adjust to index (ViewColumn.ONE => 1)
}

throw new Error(`invalid 'EditorGroupColumn'`);
}
```
`ViewColumn` has since been expanded to include `Four` through `Nine`, and opening 4 or more editor groups in a grid returns the respective `ViewColumn` number (not `undefined`).
3. **When `TextEditor.viewColumn` is actually `undefined`:**
It is only `undefined` when the editor is an embedded editor not placed in a main editor group (e.g. Peek Views, inline diff widgets, inline chat widgets).

---

### Historical Context:

1. **May 20, 2018 — PR #49599 ([commit `dd5afa5`](https://github.com/microsoft/vscode/commit/dd5afa5bcc5263f62f66407fc8742bf59ee66b7c)):**
When introducing Grid Editor Layout, the word `"three"` was initially removed from both `TextEditor.viewColumn` and `WebviewPanel.viewColumn`.
2. **May 22, 2018 — PR #49599 ([commit `0f8ef8c`](https://github.com/microsoft/vscode/commit/0f8ef8cb0ae7654dda18794e1ced102353145e36)):**
At that point in 2018, `ViewColumn` only defined `One`, `Two`, and `Three`. The runtime converter explicitly returned `undefined` for `position > 2`. `"or when the editor column is larger than three"` was added as a doc fix to document that temporary runtime limitation.
3. **June 2018 — Test Item #52315:**
In the grid layout test plan ([#52315](https://github.com/microsoft/vscode/issues/52315)), the verification checklist explicitly verified:
`[x] Verify textEditor.viewColumn is always defined for an editor in the grid even if many are opened`
4. **Subsequent updates:**
`ViewColumn` was later expanded up to `Nine`, and the converter was made dynamic (`position + 1`). Other places like `WebviewPanel.viewColumn` remained clean (`"one of the editor view columns"`), but `TextEditor.viewColumn` retained this legacy note.

---

### Proposed Fix:

Remove `, or when the editor column is larger than three.` from `src/vscode-dts/vscode.d.ts`:

```diff
/**
* The column in which this editor shows. Will be `undefined` in case this
- * isn't one of the main editors, e.g. an embedded editor, or when the editor
- * column is larger than three.
+ * isn't one of the main editors, e.g. an embedded editor.
*/
readonly viewColumn: ViewColumn | undefined;
```

I would be happy to submit a PR for this change.

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.