The doc-sniffing dog
knotbin.com
1# 🐶 Doggo
2
3> A loyal companion for your documentation journey! Doggo sniffs out undocumented exports in your Deno packages and helps you achieve 100% JSDoc coverage.
4
5```
6 __
7 (___()'`;
8 /,___ /`
9 \\" \\ "Woof! Let's document that code!"
10```
11
12[](https://opensource.org/licenses/MIT)
13[](https://deno.land)
14
15## 🦴 What is Doggo?
16
17Doggo is a good boy who helps you maintain documentation quality in your Deno projects! This CLI tool analyzes JSDoc documentation coverage of exported/public symbols in Deno packages, making sure every export has proper documentation - because well-documented code is a treat for everyone! 🍖
18
19### 🐾 Key Features
20
21- 🔍 **Sniffs Out Exports** - Automatically detects all exported symbols (functions, classes, interfaces, types, constants, variables, enums)
22- 📝 **JSDoc Tracking** - Checks which exports have been properly documented with JSDoc
23- 🎯 **Smart Fetch** - When a `deno.json` with `exports` field is found, analyzes only the actual public API (no chasing squirrels!)
24- 🏢 **Pack Support** - Analyzes all members in a Deno workspace with aggregate statistics
25- 📊 **Detailed Reports** - Get coverage percentages overall and by symbol type
26- 🎨 **Pretty Output** - Color-coded terminal output that's easy on the eyes
27- ⚡ **Fast & Lightweight** - Built with Deno's standard library (no heavy dependencies to slow us down!)
28
29## 🚀 Quick Start
30
31### Fetch the ball... I mean, analyze your code!
32
33```bash
34# Let Doggo analyze the current directory
35deno run --allow-read https://deno.land/x/doggo/main.ts
36
37# Point Doggo to a specific directory
38deno run --allow-read https://deno.land/x/doggo/main.ts ./src
39
40# Analyze a single file
41deno run --allow-read https://deno.land/x/doggo/main.ts ./src/module.ts
42```
43
44### 🏠 Train Doggo (Install)
45
46```bash
47# Install Doggo as a good boy on your system
48deno install --allow-read -n doggo https://deno.land/x/doggo/main.ts
49
50# Now you can call Doggo anytime!
51doggo
52doggo ./src
53doggo --help
54```
55
56### 🎾 Workspace Mode
57
58```bash
59# Doggo automatically detects workspace configuration
60doggo
61
62# Force workspace mode
63doggo --workspace
64```
65
66### 🦴 Using with Deno Tasks
67
68Add to your `deno.json`:
69```json
70{
71 "tasks": {
72 "doc:check": "doggo",
73 "doc:check:workspace": "doggo --workspace"
74 }
75}
76```
77
78Then run:
79```bash
80deno task doc:check
81```
82
83## 🐕 Commands & Options
84
85```
86Doggo - JSDoc Coverage Analyzer for Good Boys and Girls
87
88Usage:
89 doggo [options] [path]
90
91Options:
92 -h, --help Show help (Doggo does tricks!)
93 -v, --version Show version (Doggo's age in dog years)
94 -p, --path Path to analyze (where should Doggo sniff?)
95 -w, --workspace Force workspace mode (analyze the whole pack!)
96
97Examples:
98 doggo # Analyze current directory
99 doggo ./src # Analyze specific directory
100 doggo ./src/module.ts # Analyze single file
101 doggo --workspace # Analyze all workspace members
102```
103
104## 🎯 What Doggo Analyzes
105
106### 🏢 Workspace Mode (The Pack)
107When Doggo finds a `workspace` field in `deno.json`:
108- Analyzes each pack member individually
109- Provides per-member documentation statistics
110- Shows aggregate statistics for the entire pack
111- Barks at members that need documentation improvements
112
113### 🎯 Smart Mode (Following the Scent)
114When a `deno.json` or `deno.jsonc` file with an `exports` field is found:
115- Traces the actual public API from the entry point(s)
116- Only analyzes symbols that users actually see
117- Ignores internal implementation (no digging in the backyard!)
118- Provides accurate coverage for your public API
119
120### 🔍 Full Analysis Mode (Sniffing Everything)
121When no `deno.json` with exports is found:
122- Analyzes all exported symbols in the codebase
123- Comprehensive coverage reporting
124- Great for internal packages or during development
125
126### 📦 Supported Exports
127
128Doggo can detect and analyze:
129- **Functions** - Regular functions, async functions, arrow functions
130- **Classes** - Class declarations with their methods
131- **Interfaces** - TypeScript interface definitions
132- **Types** - Type aliases and type definitions
133- **Constants** - Exported const declarations
134- **Variables** - Exported let/var declarations
135- **Enums** - TypeScript enum definitions
136- **Default Exports** - Default exported symbols
137
138### 🚫 What Doggo Ignores
139
140Good boys know not to dig in:
141- `node_modules/` directory
142- `.git/` directory
143- `dist/`, `build/`, `coverage/` directories
144- Test files (`*.test.*`, `*.spec.*`, `test/`, `tests/`, `*_test.*`)
145
146## 🎨 Example Output
147
148### Single Package (Good Boy Mode)
149```
150🐶 Analyzing Deno Package Documentation Coverage
151
152Path: /path/to/your/package
153
154Found deno.json with exports: ./mod.ts
155
156Sniffing out public API from export entry points...
157
158📝 Undocumented Exports (Doggo found these!):
159
160 src/utils.ts:
161 ✗ formatDate [function]:67
162
163 mod.ts:
164 ✗ LogLevel [type]:45
165
166📊 Documentation Coverage Summary
167
168──────────────────────────────────────────────────
169 Total Exports: 8
170 Documented: 6
171 Undocumented: 2
172 Coverage: 75%
173──────────────────────────────────────────────────
174
175 📈 Documentation needs improvement (Doggo wants treats!)
176```
177
178### Workspace Analysis (Pack Report)
179```
180🏢 Analyzing Deno Workspace (The Pack!)
181
182Root: /path/to/workspace
183Members: 3
184
185🐕 Analyzing common...
186 ⚡ common 10 exports, 60% documented
187 └─ Entry: ./mod.ts
188
189🐕 Analyzing bytes...
190 ✗ bytes 14 exports, 50% documented
191 └─ Entry: ./mod.ts
192
193📊 Pack Summary
194────────────────────────────────────────────────────────────
195 Overall Statistics:
196 Total Members: 3
197 Total Exports: 37
198 Documented: 20
199 Coverage: 54%
200
201 ⚠️ Pack members needing training:
202 - bytes (50%)
203
204 ⚠️ The pack needs better documentation!
205```
206
207## 🏆 Coverage Indicators
208
209Doggo's tail wags differently based on your coverage:
210
211- 🏆 **100%** - Perfect! Doggo is doing zoomies!
212- ✨ **90-99%** - Excellent! Tail wagging intensifies!
213- 👍 **80-89%** - Good boy! Happy tail wags
214- 📈 **60-79%** - Needs improvement (Doggo is concerned)
215- ⚠️ **40-59%** - Poor coverage (Sad puppy eyes)
216- 🚨 **0-39%** - Critical! (Doggo is hiding under the bed)
217
218## 💡 JSDoc Examples
219
220### ✅ Good Boy (Documented)
221```typescript
222/**
223 * Calculates the number of dog treats needed.
224 * @param dogs The number of dogs
225 * @param treatsPerDog Treats each dog should get
226 * @returns Total number of treats needed
227 */
228export function calculateTreats(dogs: number, treatsPerDog: number): number {
229 return dogs * treatsPerDog;
230}
231```
232
233### ❌ Bad Boy (Needs Documentation)
234```typescript
235export function calculateTreats(dogs: number, treatsPerDog: number): number {
236 return dogs * treatsPerDog;
237}
238```
239
240## 🔧 How Doggo Works
241
242### When sniffing a workspace:
2431. **Detect Pack** - Reads `deno.json` to find workspace members
2442. **Analyze Each Member** - Individually checks each pack member
2453. **Aggregate Results** - Combines statistics across all members
2464. **Generate Report** - Shows both individual and pack-wide metrics
247
248### When following an exports scent:
2491. **Load Configuration** - Reads `deno.json` to find the `exports` field
2502. **Trace Public API** - Follows all re-exports and direct exports
2513. **Symbol Resolution** - Tracks `export { ... } from` statements
2524. **JSDoc Detection** - Checks for JSDoc comments on source definitions
2535. **Report Generation** - Shows only public API symbols
254
255### When sniffing everything:
2561. **File Discovery** - Recursively finds all source files
2572. **Export Detection** - Identifies all exported symbols
2583. **JSDoc Detection** - Checks for JSDoc comments above exports
2594. **Statistics Calculation** - Computes coverage percentages
2605. **Report Generation** - Outputs formatted report
261
262## 🦴 Configuration
263
264### Working with deno.json
265
266Doggo automatically detects your configuration:
267
268```json
269{
270 "name": "@your-org/package",
271 "version": "1.0.0",
272 "exports": "./mod.ts"
273}
274```
275
276When an `exports` field is present, Doggo only analyzes symbols exported through that entry point.
277
278### Working with Workspaces
279
280For multi-package repositories:
281
282```json
283{
284 "workspace": [
285 "packages/core",
286 "packages/utils",
287 "packages/cli"
288 ]
289}
290```
291
292Doggo will analyze each member independently and provide aggregate statistics.
293
294## 🐾 Tips & Tricks
295
2961. **Start with exports** - Use `deno.json` exports field to focus on your public API
2972. **Document as you code** - It's easier to document while the code is fresh
2983. **Use meaningful descriptions** - Help users understand not just what, but why
2994. **Include examples** - Show how to use your functions
3005. **Check regularly** - Add Doggo to your CI/CD pipeline
301
302## 🤝 Contributing
303
304Doggo loves new friends! Feel free to:
305- Report bugs (Doggo doesn't like fleas!)
306- Suggest new features (Teach Doggo new tricks!)
307- Submit pull requests (Bring treats!)
308- Improve documentation (Help Doggo communicate better!)
309
310## 📄 License
311
312MIT License - Doggo is free to roam and play!
313
314## 🙏 Acknowledgments
315
316- Built with ❤️ and 🦴 for the Deno community
317- Inspired by good boys and girls everywhere
318- Special thanks to all contributors who helped train Doggo
319
320## 🐕 Why "Doggo"?
321
322Because good dogs always document their code! Plus, who doesn't love a coding companion that:
323- Never judges your code (only helps improve it)
324- Is always excited to help
325- Loyally guards your documentation quality
326- Makes coding more fun!
327
328---
329
330*Woof! Happy documenting!* 🐶
331
332**Remember:** A well-documented codebase is like a well-trained dog - everyone loves playing with it!