Skip to content

Commit 9899999

Browse files
Copilottedhudek
Copilot
and
tedhudek
committed
Create comprehensive copilot-instructions.md for Windows Driver DDI repository
Co-authored-by: tedhudek <14337110+tedhudek@users.noreply.github.com>
1 parent 0b3d2cf commit 9899999

1 file changed

Lines changed: 217 additions & 0 deletions

File tree

‎copilot-instructions.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Windows Driver Documentation DDI - Copilot Instructions
2+
3+
## Repository Overview
4+
5+
This repository contains the source files for the Windows Driver Kit (WDK) Device Driver Interface (DDI) reference documentation. The content is published to [learn.microsoft.com/windows-hardware/drivers/ddi](/windows-hardware/drivers/ddi).
6+
7+
### Purpose
8+
- Provides comprehensive API reference documentation for Windows device drivers
9+
- Covers functions, structures, enumerations, IOCTLs, callbacks, interfaces, and classes
10+
- Serves as the authoritative source for driver development APIs across hundreds of driver categories
11+
12+
## Repository Structure
13+
14+
```
15+
windows-driver-docs-ddi/
16+
├── wdk-ddi-src/content/ # Main content directory
17+
│ ├── {category}/ # Driver category directories (e.g., wificx, ntddk, etc.)
18+
│ │ ├── nf-{category}-*.md # Function documentation
19+
│ │ ├── ns-{category}-*.md # Structure documentation
20+
│ │ ├── ne-{category}-*.md # Enumeration documentation
21+
│ │ ├── ni-{category}-*.md # IOCTL documentation
22+
│ │ ├── nc-{category}-*.md # Callback documentation
23+
│ │ ├── nn-{category}-*.md # Interface documentation
24+
│ │ ├── nl-{category}-*.md # Class documentation
25+
│ │ └── index.yml # Category index
26+
│ └── docfx.json # Build configuration
27+
├── CONTRIBUTING.md # Contribution guidelines
28+
└── README.md # Repository information
29+
```
30+
31+
## File Naming Conventions
32+
33+
All documentation files follow a strict naming pattern using prefixes to indicate the type of API element:
34+
35+
### Filename Prefix Key
36+
37+
| Prefix | Type | Description | Example |
38+
|--------|------|-------------|---------|
39+
| `ne` | Enum | Enumerations and enumerated types | `ne-wificx-wifi_adapter_type.md` |
40+
| `nc` | Callback | Callback functions and function pointers | `nc-wificx-evt_wifi_device_create_adapter.md` |
41+
| `ni` | IOCTL | Input/Output Control codes | `ni-charging-ioctl_cad_disable_charging.md` |
42+
| `ns` | Structure | Data structures and unions | `ns-wificx-wifi_device_config.md` |
43+
| `nl` | Class | Classes (primarily for C++ APIs) | `nl-engextcpp-extremotedata.md` |
44+
| `nn` | Interface | COM interfaces and abstract base classes | `nn-{category}-{interface_name}.md` |
45+
| `nf` | Function | Functions and methods | `nf-wificx-wifideviceinitialize.md` |
46+
47+
### Naming Pattern
48+
Files should follow the pattern: `{prefix}-{category}-{api_name}.md`
49+
50+
Where:
51+
- `{prefix}` is one of the prefixes above
52+
- `{category}` matches the directory name
53+
- `{api_name}` is the lowercase, hyphenated version of the API name
54+
55+
## Content Structure
56+
57+
Each documentation file contains:
58+
59+
### YAML Frontmatter (Required)
60+
Every file must start with YAML frontmatter containing metadata:
61+
62+
```yaml
63+
---
64+
UID: {Unique identifier}
65+
title: {API Name} ({header file})
66+
description: {Brief description of the API}
67+
tech.root: {Technology area}
68+
ms.date: {Date in MM/DD/YYYY format}
69+
targetos: Windows
70+
keywords: ["{API Name}"]
71+
ms.keywords: {Comma-separated keywords}
72+
req.header: {Header file name}
73+
req.include-header: {Include header if different}
74+
req.target-type: {Target type}
75+
req.target-min-winverclnt: {Minimum Windows client version}
76+
req.target-min-winversvr: {Minimum Windows server version}
77+
req.lib: {Required library}
78+
req.dll: {Required DLL}
79+
req.irql: {IRQL level}
80+
req.ddi-compliance: {DDI compliance info}
81+
topic_type:
82+
- apiref
83+
api_type:
84+
- {HeaderDef|DllExport|LibDef}
85+
api_location:
86+
- {header file or library}
87+
api_name:
88+
- {API name}
89+
f1_keywords:
90+
- {API name}
91+
- {header}/{API name}
92+
dev_langs:
93+
- c++
94+
ai-usage: {ai-assisted|ai-generated}
95+
---
96+
```
97+
98+
### Required AI Usage Metadata
99+
**IMPORTANT**: All articles created or revised using AI must include the `ai-usage` metadata attribute in the YAML frontmatter.
100+
101+
- `ai-assisted`: Content was created by a human author with the help of AI. A human author reviewed and revised the content as needed.
102+
- `ai-generated`: Content was created by AI. A human author may have reviewed and revised the content as needed.
103+
104+
This metadata automatically adds a customer-facing AI disclosure to the published content.
105+
106+
### Content Sections
107+
108+
#### Standard Sections (in order):
109+
1. `## -description` - Detailed description of the API
110+
2. `## -parameters` (functions/methods only) - Parameter descriptions
111+
3. `## -struct-fields` (structures only) - Field descriptions
112+
4. `## -enum-fields` (enumerations only) - Enumeration value descriptions
113+
5. `## -returns` (functions with return values) - Return value information
114+
6. `## -remarks` - Additional usage notes, examples, and important information
115+
7. `## -see-also` - Related API references
116+
117+
#### Parameter/Field Format:
118+
```markdown
119+
### -param ParameterName
120+
Brief description of the parameter.
121+
122+
### -field FieldName
123+
Brief description of the field.
124+
```
125+
126+
## Link Formatting Guidelines
127+
128+
### Site-Relative Links (Required)
129+
**IMPORTANT**: Use site-relative links instead of fully qualified URLs for learn.microsoft.com content.
130+
131+
✅ **Correct:**
132+
```markdown
133+
[Windows Hardware Developer](/windows-hardware)
134+
[Driver Development](/windows-hardware/drivers)
135+
[API Reference](/windows-hardware/drivers/ddi)
136+
```
137+
138+
❌ **Incorrect:**
139+
```markdown
140+
[Windows Hardware Developer](https://learn.microsoft.com/windows-hardware)
141+
[Driver Development](https://learn.microsoft.com/windows-hardware/drivers)
142+
[API Reference](https://learn.microsoft.com/windows-hardware/drivers/ddi)
143+
```
144+
145+
### Cross-References
146+
- Link to other APIs using relative paths: `[OtherFunction](nf-category-otherfunction.md)`
147+
- Link to structures/enums: `[STRUCTURE_NAME](ns-category-structure_name.md)`
148+
- Use **bold** formatting for API names in text: `**ApiName**`
149+
150+
### External Links
151+
External links (non-learn.microsoft.com) should use full URLs:
152+
```markdown
153+
[Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk/)
154+
```
155+
156+
## Writing Guidelines
157+
158+
### Style and Tone
159+
- Use clear, concise technical language
160+
- Write in third person
161+
- Use active voice when possible
162+
- Be consistent with terminology across related APIs
163+
164+
### Content Quality
165+
- Ensure all parameters/fields are documented
166+
- Include practical usage examples in -remarks when helpful
167+
- Cross-reference related APIs in -see-also sections
168+
- Verify technical accuracy of all information
169+
170+
### Common Patterns
171+
- Functions: Focus on purpose, parameters, return values, and usage patterns
172+
- Structures: Document each field, memory layout considerations, and usage context
173+
- Enumerations: Explain each value and when it's used
174+
- IOCTLs: Include input/output buffer descriptions and operation details
175+
176+
## Build and Validation
177+
178+
The repository uses DocFX for building documentation. Key configuration is in `docfx.json`.
179+
180+
### Local Validation
181+
- Ensure YAML frontmatter is valid
182+
- Verify all internal links resolve correctly
183+
- Check that filename conventions are followed
184+
- Validate that required metadata is present
185+
186+
### Content Review Checklist
187+
- [ ] Correct filename prefix used
188+
- [ ] YAML frontmatter complete and valid
189+
- [ ] AI usage metadata included if AI was used
190+
- [ ] Site-relative links used for learn.microsoft.com content
191+
- [ ] All required sections present
192+
- [ ] Technical accuracy verified
193+
- [ ] Cross-references added to related APIs
194+
- [ ] Examples provided where helpful
195+
196+
## Categories and Technology Areas
197+
198+
The repository covers numerous driver categories including but not limited to:
199+
- Audio (acx*, dmusicks, dmusprop, hdaudio, etc.)
200+
- Display (d3d*, dispmprt, video, etc.)
201+
- Network (ndis*, net*, wifi*, etc.)
202+
- Storage (storage*, scsi*, ata, etc.)
203+
- USB (usb*, ucm*, etc.)
204+
- Sensors (sensors*, gnss*, etc.)
205+
- And many more specialized driver areas
206+
207+
Each category has its own directory structure and may have category-specific conventions documented in local README files.
208+
209+
## Contributing
210+
211+
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines, including:
212+
- Pull request process
213+
- Code review requirements
214+
- Microsoft Contributor License Agreement (CLA)
215+
- Style guide adherence
216+
217+
For questions or issues, create an issue in this repository or contact the Windows driver documentation team.

0 commit comments

Comments
 (0)