Add API documentation

[tothambrus11]

As a frequent happy user of this library, I was missing API docs from declarations on this library, often browsing the specification on what certain properties are.

I used Claude Opus 4.6 Thinking with Windsurf to add in-source documentation to this library. I totally understand if this kind of contribution is not welcome, I just wanted to be upfront about it. I tried my best to ensure the quality of these docs, see my process below. If this is merged, I can also follow the same process for documenting LanguageServer.

I made the prompt based on Hylo's coding conventions for documentation:

You are asked to introduce documentation to this library strictly according to the official language server protocol specification at https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ Please follow the guidelines defined below. Do not modify any API, only add the documentation comments.

Our conventions are based on the [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).

Documentation enables local reasoning - it's a shortcut for understanding so readers can avoid looking up implementation
or usages to infer meaning.

- Every declaration outside a function body must have a documentation comment that describes its contract.
  - Start with a summary sentence fragment.
    - Describe what a function or method does and what it returns.
    - Describe what a property or type is.
    - Separate the fragment from any additional documentation with a blank line and end it with a period.

  - Preconditions, postconditions and invariants obviously implied by the summary need not be explicitly documented.

  - Declarations that fulfill protocol requirements are exempted when nothing useful can be added to the documentation
    of the protocol requirement itself.

- Document the performance of every operation that doesn't execute in constant time and space, unless it's obvious from
  the summary.
- Test cases need not be documented, but should have a descriptive function name.

- Phrasing conventions:
  - Omit needless words: don't repeat the receiver's type, don't write the, given, of self,
    of the current object when context makes these obvious.
  - Use iff instead of if where applicable.
  - Use <...>, if any. for optional values where the absence reason is obvious. Otherwise:
    <...> if <condition>, nil otherwise. 
  - Document preconditions with - Requires:. If multiple preconditions apply, use a markdown list below - Requires:.
- Conformance implementations are exempt from documentation when nothing useful can be added beyond the protocol
  requirement itself.
- For trivial constructors, use `/// Creates an instance from its parts.`
- Test cases don't need to be documented, but should have a descriptive function name.
- For types, the summary should say what the type *is*. For functions and subscripts, it should say what they *do* (e.g. returns, yields ...).
- Describe if there is a significance in the element order of an array.

After planning, it came up with the following plan:

Plan.md

# Document the LanguageServerProtocol Library

Add documentation comments to all 42 source files following the LSP 3.17 specification and the project's documentation conventions.

## Conventions Summary

- Use `///` style (convert existing `/** */` comments)
- Summary sentence fragment describing what a type *is* or what a function *does*, ending with a period
- Trivial initializers: `/// Creates an instance from its parts.`
- Skip conformance extensions when nothing useful can be added
- Use LSP spec descriptions as the source of truth for semantic meaning, copying exact phrasing where possible.
- Follow phrasing conventions: omit needless words, use `iff` over `if`, `Returns ..., if any` for optionals.

## Batches

### Batch 1 – Base & Core Types
1. `BaseProtocol.swift` – typealiases (`LSPAny`, `URI`, `DocumentUri`, `ProgressToken`), `CancelParams`, `ProgressParams`, `LogTraceParams`, `TraceValue`, `SetTraceParams`, `ValueSet`, `LanguageIdentifier`, `DocumentFilter`, `DocumentSelector`, `TextDocumentIdentifier`
2. `BasicStructures.swift` – `Position`, `LSPRange`, `TextDocumentItem`, `VersionedTextDocumentIdentifier`, `Location`, `Command`, `SymbolKind`, `MarkupKind`, `TextDocumentPositionParams`, `LanguageStringPair`, `MarkedString`, `MarkupContent`, `LocationLink`
3. `TwoTypeOption.swift` – generic union type
4. `ThreeTypeOption.swift` – generic union type
5. `Utility.swift`
6. `ErrorCodes.swift` – convert existing `/** */` to `///`

### Batch 2 – Server Lifecycle & General
7. `General.swift` – `Tracing`, `InitializeParams`, `ServerInfo`, `InitializationResponse`, `InitializedParams`; convert existing `/** */`
8. `LanguageServerProtocol.swift` – `ProtocolError`, `ClientEvent`, `ServerEvent`, `ClientNotification`, `ClientRequest`, `ServerNotification`, `ServerRequest`
9. `Client.swift`
10. `ClientCapabilities.swift`
11. `ServerCapabilities.swift`

### Batch 3 – Text Synchronization & Window
12. `TextSynchronization.swift` – `TextDocumentSyncKind`, `DidOpenTextDocumentParams`, etc.
13. `Window.swift` – `MessageType`, `LogMessageParams`, `ShowMessageParams`, `ShowDocumentParams`, `WorkDoneProgressCreateParams`, `ShowDocumentResult`
14. `Window/ShowMessageRequest.swift` – `MessageActionItem`, `ShowMessageRequestParams`, `ShowMessageRequestResponse`

### Batch 4 – Workspace
15. `Workspace.swift`
16. `Workspace/ApplyEdit.swift`
17. `Workspace/Configuration.swift`
18. `Workspace/ExecuteCommand.swift`
19. `Workspace/Folders.swift`
20. `Workspace/Symbol.swift`
21. `Workspace/WillCreateFiles.swift`
22. `Workspace/WillDeleteFiles.swift`
23. `Workspace/WillRenameFiles.swift`

### Batch 5 – Language Features (A-D)
24. `LanguageFeatures/CallHeirarchy.swift`
25. `LanguageFeatures/CodeAction.swift`
26. `LanguageFeatures/CodeLens.swift`
27. `LanguageFeatures/ColorPresentation.swift`
28. `LanguageFeatures/Completion.swift`
29. `LanguageFeatures/Declaration.swift`
30. `LanguageFeatures/Definition.swift`
31. `LanguageFeatures/Diagnostics.swift`
32. `LanguageFeatures/DocumentColor.swift`
33. `LanguageFeatures/DocumentHighlight.swift`
34. `LanguageFeatures/DocumentLink.swift`
35. `LanguageFeatures/DocumentSymbol.swift`

### Batch 6 – Language Features (F-Z)
36. `LanguageFeatures/FoldingRange.swift`
37. `LanguageFeatures/Formatting.swift`
38. `LanguageFeatures/Hover.swift`
39. `LanguageFeatures/Implementation.swift`
40. `LanguageFeatures/InlayHint.swift`
41. `LanguageFeatures/LinkedEditingRange.swift`
42. `LanguageFeatures/Moniker.swift`
43. `LanguageFeatures/OnTypeFormatting.swift`
44. `LanguageFeatures/References.swift`
45. `LanguageFeatures/Rename.swift`
46. `LanguageFeatures/SelectionRange.swift`
47. `LanguageFeatures/SemanticTokens.swift`
48. `LanguageFeatures/SignatureHelp.swift`
49. `LanguageFeatures/TypeDefinition.swift`
50. `LanguageFeatures/TypeHeirarchy.swift`

### Batch 7 – Client & Framing & Additions
51. `Client/ServerConnection.swift`
52. `Client/JSONRPCServerConnection.swift`
53. `Client/MockServer.swift`
54. `Framing/AsyncByteSequence.swift`
55. `Framing/AsyncMessageFramingSequence.swift`
56. `Framing/DataChannel+MessageFraming.swift`
57. `Framing/MessageFraming.swift`
58. `Additions/AsyncStreamPolyfill.swift`
59. `Additions/NSRegularExpression+Matching.swift`
60. `Additions/Protocol+Mutating.swift`
61. `Additions/ServerCapabilities+Extensions.swift`
62. `Additions/Snippet.swift`
63. `Additions/TokenRepresentation.swift`

## Approach

- For each file, read the LSP spec section(s) relevant to the types in that file
- Write `///` doc comments on every public type, property, method, enum case, and typealias
- Use the spec's description as the basis but adapt phrasing to match Swift conventions
- Do not modify any API signatures, logic, or non-doc comments
- Run `swift test` after every batch.

Review

AI-assisted review

After completion, I executed a separate review of the documentation 2 times, during which it completed API documentation it missed previously, and corrected 3 comments that were slightly wordy or inaccurate.

Manual review

After the AI-assisted review, I read through the PR quickly to see if there is anything obviously inaccurate/badly phrased. I noticed that it removed the @since tags from existing comments, so I run another pass to update them.

add `@since`

In the last commit, several comments mentioning the @since were removed. We need these 
information whenever the LSP doc mentions it. Please add them back where they were 
present before, and in addition, whenever the specification mentioned it explicitly.

I run another pass of AI-assisted review to check if the - Since annotations match up with the LSP specification's information. There were no inaccuracies found in this pass.

[tothambrus11]

Note: see #34

This implementation should be corrected.

[tothambrus11]

#37

[mattmassicotte]

Hello, and glad the library has been useful.

Just so I understand correctly, you have not read each change personally?

[tothambrus11]

Yes, good call. I'll read it more carefully today.

[mattmassicotte]

No no, that's ok! I wasn't trying to make work for you. I just wanted to better understand.

I won't lie, I'm quite hesitant here. First, this is very large number of changes. But, more so, the lack of documentation prompts you to look at the official spec. Which I think might be ok compared to the promise of local documentation that was not actually human written?

[tothambrus11]

Yeah, I get that. Better have nothing but reliable than something that might be inaccurate. I'll see if I can do this copying manually, it probably wouldn't take much longer than just reviewing the PR in detail, and then we can be 100% accurate.