Skip to content

Commit 58451f5

Browse files
brunoborgesbrunoborges
committed
Add documentation coverage assessment prompt and skill file
1 parent 765e362 commit 58451f5

2 files changed

Lines changed: 216 additions & 0 deletions

File tree

‎.github/prompts/documentation-coverage.prompt.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Documentation Coverage Assessment
2+
3+
You are an expert Java developer tasked with assessing whether the documentation in `src/site/markdown/` adequately covers the functionality implemented in the Java SDK.
4+
5+
## Objective
6+
7+
Analyze the Java SDK source code and compare it against the existing documentation to:
8+
1. **Identify undocumented features** - Functionality in code that lacks documentation
9+
2. **Find outdated documentation** - Docs that don't match current implementation
10+
3. **Assess documentation quality** - Are documented features explained with examples?
11+
12+
## Assessment Process
13+
14+
### Step 1: Inventory Public API
15+
16+
Extract all public classes, methods, and features from the SDK:
17+
18+
```bash
19+
# List all public classes in core package
20+
grep -l "public class\|public interface\|public enum" src/main/java/com/github/copilot/sdk/*.java
21+
22+
# List all public classes in json package (DTOs)
23+
grep -l "public class" src/main/java/com/github/copilot/sdk/json/*.java
24+
25+
# List all event types
26+
ls src/main/java/com/github/copilot/sdk/events/
27+
```
28+
29+
### Step 2: Inventory Documentation
30+
31+
List all documentation files:
32+
33+
```bash
34+
ls src/site/markdown/
35+
```
36+
37+
Read each documentation file to understand current coverage.
38+
39+
### Step 3: Map Features to Documentation
40+
41+
For each major feature area, determine if it's documented:
42+
43+
#### CopilotClient Features
44+
45+
Examine `CopilotClient.java` for public methods:
46+
47+
```bash
48+
grep "public.*(" src/main/java/com/github/copilot/sdk/CopilotClient.java | grep -v "@"
49+
```
50+
51+
| Method | Purpose | Documented In | Status |
52+
|--------|---------|---------------|--------|
53+
| `start()` | Start the client | ? | ✅/❌ |
54+
| `stop()` | Stop the client | ? | ✅/❌ |
55+
| `createSession()` | Create a new session | ? | ✅/❌ |
56+
| `resumeSession()` | Resume existing session | ? | ✅/❌ |
57+
| `deleteSession()` | Delete a session | ? | ✅/❌ |
58+
| `listSessions()` | List all sessions | ? | ✅/❌ |
59+
| `listModels()` | List available models | ? | ✅/❌ |
60+
| `getStatus()` | Get client status | ? | ✅/❌ |
61+
| `getAuthStatus()` | Get auth status | ? | ✅/❌ |
62+
| `ping()` | Ping the server | ? | ✅/❌ |
63+
64+
#### CopilotSession Features
65+
66+
Examine `CopilotSession.java` for public methods:
67+
68+
```bash
69+
grep "public.*(" src/main/java/com/github/copilot/sdk/CopilotSession.java | grep -v "@"
70+
```
71+
72+
| Method | Purpose | Documented In | Status |
73+
|--------|---------|---------------|--------|
74+
| `send()` | Send a message | ? | ✅/❌ |
75+
| `sendAndWait()` | Send and wait for response | ? | ✅/❌ |
76+
| `on()` | Subscribe to events | ? | ✅/❌ |
77+
| `registerTools()` | Register custom tools | ? | ✅/❌ |
78+
| `getMessages()` | Get conversation history | ? | ✅/❌ |
79+
| `abort()` | Abort current operation | ? | ✅/❌ |
80+
81+
#### SessionConfig Options
82+
83+
Examine `SessionConfig.java` for configurable options:
84+
85+
```bash
86+
grep "public.*set\|private.*;" src/main/java/com/github/copilot/sdk/json/SessionConfig.java
87+
```
88+
89+
| Option | Purpose | Documented | Example Provided |
90+
|--------|---------|:----------:|:----------------:|
91+
| `model` | Model to use | ✅/❌ | ✅/❌ |
92+
| `tools` | Custom tools | ✅/❌ | ✅/❌ |
93+
| `systemMessage` | System prompt | ✅/❌ | ✅/❌ |
94+
| `streaming` | Enable streaming | ✅/❌ | ✅/❌ |
95+
| `mcpServers` | MCP integration | ✅/❌ | ✅/❌ |
96+
| `hooks` | Session hooks | ✅/❌ | ✅/❌ |
97+
| `infiniteSessions` | Long sessions | ✅/❌ | ✅/❌ |
98+
| `skillDirectories` | Skills config | ✅/❌ | ✅/❌ |
99+
| `customAgents` | Custom agents | ✅/❌ | ✅/❌ |
100+
101+
#### Event Types
102+
103+
Check which events are documented:
104+
105+
```bash
106+
grep "TYPE_MAP.put" src/main/java/com/github/copilot/sdk/events/SessionEventParser.java
107+
```
108+
109+
| Event Type | Event Class | Documented | Example |
110+
|------------|-------------|:----------:|:-------:|
111+
| `session.start` | `SessionStartEvent` | ✅/❌ | ✅/❌ |
112+
| `session.idle` | `SessionIdleEvent` | ✅/❌ | ✅/❌ |
113+
| `assistant.message` | `AssistantMessageEvent` | ✅/❌ | ✅/❌ |
114+
| ... | ... | ... | ... |
115+
116+
#### Hooks
117+
118+
Check `SessionHooks.java` for hook types:
119+
120+
```bash
121+
grep "private.*Handler" src/main/java/com/github/copilot/sdk/json/SessionHooks.java
122+
```
123+
124+
| Hook | Handler Interface | Documented | Example |
125+
|------|-------------------|:----------:|:-------:|
126+
| Pre-tool use | `PreToolUseHandler` | ✅/❌ | ✅/❌ |
127+
| Post-tool use | `PostToolUseHandler` | ✅/❌ | ✅/❌ |
128+
| User prompt submitted | `UserPromptSubmittedHandler` | ✅/❌ | ✅/❌ |
129+
| Session lifecycle | `SessionLifecycleHandler` | ✅/❌ | ✅/❌ |
130+
131+
### Step 4: Check Documentation Quality
132+
133+
For each documented feature, verify:
134+
135+
1. **Accurate description** - Does it match current implementation?
136+
2. **Code example** - Is there a working code snippet?
137+
3. **Complete coverage** - Are all parameters/options explained?
138+
4. **Up to date** - Does it reflect the current API?
139+
140+
## Report Format
141+
142+
### Documentation Coverage Summary
143+
144+
| Category | Total Features | Documented | Coverage |
145+
|----------|----------------|------------|----------|
146+
| Client Methods | X | X | X% |
147+
| Session Methods | X | X | X% |
148+
| Config Options | X | X | X% |
149+
| Events | X | X | X% |
150+
| Hooks | X | X | X% |
151+
| **Overall** | **X** | **X** | **X%** |
152+
153+
### Undocumented Features
154+
155+
Features that exist in code but have no documentation:
156+
157+
| Feature | Location | Priority | Notes |
158+
|---------|----------|----------|-------|
159+
| Feature name | Class/method | High/Medium/Low | Why it matters |
160+
161+
### Documentation Gaps
162+
163+
Existing docs that need enhancement:
164+
165+
| Document | Gap | Recommendation |
166+
|----------|-----|----------------|
167+
| `getting-started.md` | Missing X | Add section on X |
168+
| `advanced.md` | Outdated API | Update to match code |
169+
170+
### Missing Documentation Files
171+
172+
Topics that warrant dedicated documentation:
173+
174+
| Topic | Why Needed | Suggested File |
175+
|-------|------------|----------------|
176+
| Hooks | Complex feature | `hooks.md` |
177+
| Error Handling | Common need | `error-handling.md` |
178+
179+
### Recommendations
180+
181+
#### High Priority
182+
1. Document feature X - used frequently, no docs
183+
2. Update docs for Y - API changed
184+
185+
#### Medium Priority
186+
1. Add examples for Z
187+
2. Improve explanation of W
188+
189+
#### Nice to Have
190+
1. Add troubleshooting guide
191+
2. Add FAQ section
192+
193+
## Key Files
194+
195+
### Source Code
196+
- `src/main/java/com/github/copilot/sdk/CopilotClient.java`
197+
- `src/main/java/com/github/copilot/sdk/CopilotSession.java`
198+
- `src/main/java/com/github/copilot/sdk/json/SessionConfig.java`
199+
- `src/main/java/com/github/copilot/sdk/json/SessionHooks.java`
200+
- `src/main/java/com/github/copilot/sdk/events/SessionEventParser.java`
201+
202+
### Documentation
203+
- `src/site/markdown/index.md` - Landing page
204+
- `src/site/markdown/getting-started.md` - Quick start guide
205+
- `src/site/markdown/documentation.md` - API reference
206+
- `src/site/markdown/advanced.md` - Advanced topics
207+
- `src/site/markdown/mcp.md` - MCP integration

‎.github/skills/documentation-coverage/SKILL.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
```skill
2+
---
3+
name: documentation-coverage
4+
description: Assess whether the documentation in src/site/markdown/ adequately covers the Java SDK functionality.
5+
license: MIT
6+
---
7+
8+
Follow instructions in the [documentation-coverage prompt](../../prompts/documentation-coverage.prompt.md) to analyze gaps between the SDK's implemented features and its documentation.
9+
```

0 commit comments

Comments
 (0)