Brace Notes

Finish a { } block and Brace Notes writes a one-line comment above it saying what the code inside does — and a short comment at the end of each line inside it.

// 📝 Describes what an image converter must provide.
protocol ImageConverter {
    var inputTypes: [UTType] { get } // a list of file types it can read, like [.image]
    var outputTypes: [UTType] { get } // a list of file types it can make, like [.jpeg, .png, .heic]
}

Variables and properties get a tiny example too:

@State private var fileName = ""   // file name, like "cat.png" (empty = none yet)
@State private var isLoading = false // true when loading (starts false)

Learning mode: keyword list

Brace Notes is made for people learning to code, so it keeps a 📘 list right under your imports explaining every keyword the file uses. New keywords are added to it as you write:

import SwiftUI

// 📘 Keywords used in this file:
// 📘 import: brings in code from another file or library so you can use it
// 📘 struct: groups related values into one type; copied when assigned (a "value type")
// 📘 @State: SwiftUI saves this value for the view and redraws the screen whenever it changes
// 📘 private: only code inside this same type (in this file) can use this
// 📘 var: declares a variable — its value can change later

// 📝 Struct `PickerView` — holds `fileName` and `showPicker`.
struct PickerView: View {
    @State private var fileName = ""       // file name, like "cat.png" (empty = none yet)
    @State private var showPicker = false  // true when picker is shown (starts false)
}

Names you make up yourself (like showPicker) aren't keywords — those are explained by the end-of-line comment. Set braceNotes.explainKeywords to off to turn the list off.

Lines that already have a comment are never touched, so your own comments are safe, and when you add new lines later only those get a comment.

When does a note appear?

• When you type the closing } of a block, or
• when you move your cursor out of a block you just edited (this covers VS Code's auto-closed braces).

If you edit the block again later, the note is updated in place rather than duplicated (notes are recognised by the 📝 marker).

By default it notes whole units — functions, methods, top-level if/for blocks, objects and CSS rules — not every little if inside a function. Turn on braceNotes.nestedBlocks to note inner blocks too.

Where do the descriptions come from?

1. AI (if available): with GitHub Copilot (or any extension that provides a VS Code language model) installed, Brace Notes asks the model for a one-sentence summary. VS Code will ask you once to allow this.
2. Built-in describer: otherwise it reads the code itself and writes something like Function \addItem(item)` — checks a condition, calls `this.items.push`, can throw an error and returns `this.items.length`.`

Switches (bottom-right of VS Code)

Click Brace Notes in the status bar to open the switches menu:

• Everything — turns all automatic comments on or off (your other choices are remembered)
• Describe this block — the 📝 note above each block
• Comment every line — the short comments at the end of lines
• Keyword list at the top — the 📘 list under the imports

It also has two clean-up actions (both ask first, and Ctrl+Z undoes them):

• Delete Brace Notes’ 📝 and 📘 lines — removes the block notes and keyword list, keeps your own comments
• Delete ALL comments in this file — removes every comment, including ones you wrote

Switching off hides, switching on brings back. Turning a switch off removes those comments from every open file, and Brace Notes remembers them. Turning it back on puts the same comments back (including any you edited), and writes new ones only where something is missing. Your own comments are never touched — Brace Notes keeps track of which end-of-line comments it wrote. If it finds some it can't be sure about (e.g. written by an older version), it asks before removing them.

The status bar shows which ones are on, e.g. Brace Notes 📝💬📘.

Commands

Settings

braceNotes.enabled, braceNotes.blockComments (the 📝 note), braceNotes.lineComments (end-of-line comments), braceNotes.lineExamples (example values), braceNotes.explainKeywords (📘 lines), braceNotes.learnMarker, braceNotes.alignLineComments, braceNotes.lineCommentMaxLength, braceNotes.useAI, braceNotes.aiModelFamily, braceNotes.marker, braceNotes.nestedBlocks, braceNotes.minLines, braceNotes.maxLength, braceNotes.languages.

Install

• Quick: in VS Code open the Extensions view → … menu → Install from VSIX… → pick brace-notes-0.8.1.vsix in this folder.
• Try it without installing: open this folder in VS Code and press F5; a new window opens with the extension running.
• Rebuild the VSIX after changes: npm run package.