docscribe 1.6.1 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +258 -51
- data/exe/docscribe-client +26 -7
- data/lib/docscribe/cli/config_builder.rb +69 -8
- data/lib/docscribe/cli/config_dump.rb +88 -7
- data/lib/docscribe/cli/coverage.rb +5 -5
- data/lib/docscribe/cli/formatters/json.rb +74 -29
- data/lib/docscribe/cli/formatters/sarif.rb +20 -3
- data/lib/docscribe/cli/options.rb +36 -2
- data/lib/docscribe/cli/rbs_gen.rb +4 -4
- data/lib/docscribe/cli/run.rb +297 -52
- data/lib/docscribe/cli/update_types.rb +61 -17
- data/lib/docscribe/cli.rb +19 -13
- data/lib/docscribe/config/defaults.rb +2 -0
- data/lib/docscribe/config/plugin.rb +4 -4
- data/lib/docscribe/config/rbs.rb +30 -12
- data/lib/docscribe/config/sorbet.rb +3 -1
- data/lib/docscribe/config/template.rb +6 -0
- data/lib/docscribe/config/utils.rb +15 -0
- data/lib/docscribe/config/validation.rb +34 -0
- data/lib/docscribe/config.rb +35 -1
- data/lib/docscribe/infer/behavior.rb +13 -13
- data/lib/docscribe/infer/params.rb +2 -2
- data/lib/docscribe/infer/raises.rb +5 -6
- data/lib/docscribe/infer/returns.rb +1642 -151
- data/lib/docscribe/infer.rb +7 -7
- data/lib/docscribe/inline_rewriter/doc_builder.rb +551 -102
- data/lib/docscribe/inline_rewriter.rb +367 -98
- data/lib/docscribe/plugin/registry.rb +1 -0
- data/lib/docscribe/server/base.rb +73 -21
- data/lib/docscribe/server/client.rb +20 -11
- data/lib/docscribe/server/daemon.rb +209 -23
- data/lib/docscribe/server/protocol.rb +4 -4
- data/lib/docscribe/types/primitive.rb +160 -0
- data/lib/docscribe/types/rbs/provider.rb +5 -2
- data/lib/docscribe/types/sorbet/base_provider.rb +33 -1
- data/lib/docscribe/types/yard/formatter.rb +35 -6
- data/lib/docscribe/types/yard/parser.rb +32 -22
- data/lib/docscribe/types/yard/repair.rb +142 -0
- data/lib/docscribe/types/yard/validator.rb +131 -0
- data/lib/docscribe/validator/generic_compatibility.rb +698 -0
- data/lib/docscribe/validator/type_mismatch_validator.rb +287 -0
- data/lib/docscribe/version.rb +1 -1
- metadata +9 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 58018ff6ce9cc837ebe99189ccf04770567d4ca922f9a970c6157e81df7e0374
|
|
4
|
+
data.tar.gz: 8356662fe2fbd4fc3e6e9c94ff5c77c10700f8afa9159aaecf0feebcf29e8a2d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a26b97d57f0440c84ebc0a3148ab654790ffc47559dd304a595bb30c7aceb4c9ebf220e90060cf84506f95919257d50fff164dadaea000be971be5e3e65fc71c
|
|
7
|
+
data.tar.gz: 2976adfbd46d61f7488a80c65d23b7519de358742f55fcd96a3d913f35f85f9836d2e020d9b8c7d9087a0238df468d30625196a1b3d1d0a234b599f93a7e21df
|
data/README.md
CHANGED
|
@@ -78,6 +78,7 @@ docscribe -A lib
|
|
|
78
78
|
* [Installation](#installation)
|
|
79
79
|
* [Architecture](#architecture)
|
|
80
80
|
* [Data flow](#data-flow)
|
|
81
|
+
* [IDE plugin and gem interaction](#ide-plugin-and-gem-interaction)
|
|
81
82
|
* [CLI](#cli)
|
|
82
83
|
* [Exit codes](#exit-codes)
|
|
83
84
|
* [Options](#options)
|
|
@@ -167,9 +168,9 @@ Requires Ruby 2.7+.
|
|
|
167
168
|
## Architecture
|
|
168
169
|
|
|
169
170
|
Docscribe is organized into several subsystems. The CLI layer receives user input and orchestrates configuration
|
|
170
|
-
loading
|
|
171
|
-
doc lines
|
|
172
|
-
the source via a strategy
|
|
171
|
+
loading. It then delegates to the core engine, which parses source code and collects methods using an AST walker. From
|
|
172
|
+
there it builds YARD doc lines, combining heuristic type inference, external RBS/Sorbet signatures, and plugin output.
|
|
173
|
+
Finally, it rewrites the source via a strategy: safe merge or aggressive replace.
|
|
173
174
|
|
|
174
175
|
In server mode, a persistent daemon (`docscribe server`) keeps the runtime loaded and caches parsed results across
|
|
175
176
|
invocations via an LRU cache, enabling near-instant repeated checks for IDE plugins. A thin client (`docscribe-client`)
|
|
@@ -181,10 +182,17 @@ flowchart TB
|
|
|
181
182
|
Exe["exe/docscribe\nEntry point"]
|
|
182
183
|
Run["CLI::Run\nMain execution\n· expand paths\n· iterate files\n· report results"]
|
|
183
184
|
Options["CLI::Options\nARGV parsing\n(mode, strategy,\nfilters, flags)"]
|
|
185
|
+
CLIDispatch["CLI.dispatch_subcommand"]
|
|
184
186
|
InitCmd["CLI::Init\ndocscribe init\nGenerate config"]
|
|
185
187
|
GenCmd["CLI::Generate\ndocscribe generate\nScaffold plugins"]
|
|
186
188
|
SigsCmd["CLI::Sigs\ndocscribe sigs\nCheck RBS coverage"]
|
|
187
189
|
RbsGenCmd["CLI::RbsGen\ndocscribe rbs\nGenerate RBS from YARD"]
|
|
190
|
+
UpdateTypesCmd["CLI::UpdateTypes\ntwo-pass rebuild"]
|
|
191
|
+
ConfigDumpCmd["CLI::ConfigDump\ndocscribe config\n· resolved config\n· --only-changed\n· --format yaml/json/text"]
|
|
192
|
+
CoverageCmd["CLI::Coverage\ndocscribe coverage\nDocumentation coverage\n· text / json report"]
|
|
193
|
+
CheckCommentsCmd["CLI::CheckForComments\ndocscribe check_for_comments"]
|
|
194
|
+
ServerCmd["CLI::ServerCmd\ndocscribe server"]
|
|
195
|
+
JsonFormatter["CLI::Formatters::Json\nJSON offenses\n(type, source)"]
|
|
188
196
|
SarifFormatter["CLI::Formatters::Sarif\nSARIF 2.1 JSON\nCode Scanning"]
|
|
189
197
|
ConfigBuilder["CLI::ConfigBuilder\nApply CLI overrides\nto config"]
|
|
190
198
|
end
|
|
@@ -198,6 +206,9 @@ flowchart TB
|
|
|
198
206
|
RBSConfig["config/rbs.rb\nRBS provider\nfactory"]
|
|
199
207
|
SorbetConfig["config/sorbet.rb\nSorbet provider\nchain factory"]
|
|
200
208
|
PluginConfig["config/plugin.rb\nPlugin loading\nfrom YAML"]
|
|
209
|
+
ValidateCfg["config/validation.rb\nvalidate_types?"]
|
|
210
|
+
SortingCfg["config/sorting.rb\nsort_tags / tag_order"]
|
|
211
|
+
TemplateCfg["config/template.rb\ndefault YAML"]
|
|
201
212
|
end
|
|
202
213
|
|
|
203
214
|
subgraph Parsing["Parsing"]
|
|
@@ -210,12 +221,16 @@ flowchart TB
|
|
|
210
221
|
InlineRewriter["InlineRewriter\n· parse -> collect\n· deduplicate -> dispatch\n· rewrite"]
|
|
211
222
|
Collector["Collector\n< Parser::AST::Processor\nAST walker\n· find methods/attrs\n· track visibility\n· track containers"]
|
|
212
223
|
DocBuilder["DocBuilder\nGenerate YARD doc lines\n· combine inference\n· external signatures\n· plugin tags"]
|
|
224
|
+
ValidSvc["Validator\nGenericCompatibility +\nTypeMismatchValidator"]
|
|
225
|
+
RunFork["CLI::Run parallel path\n· --parallel / --jobs N\n· warm env once, then fork\n· COW-inherited RBS env\n· sequential fallback\n when fork absent"]
|
|
213
226
|
DocBlock["DocBlock\nSafe strategy:\nparse -> merge -> sort\nexisting doc blocks"]
|
|
214
227
|
SourceHelpers["SourceHelpers\nPosition/range\nutilities"]
|
|
215
228
|
end
|
|
216
229
|
|
|
217
230
|
subgraph Infer["Inference Engine"]
|
|
218
231
|
InferModule["Infer\nEntry point"]
|
|
232
|
+
InferBehavior["Infer::Behavior"]
|
|
233
|
+
InferConsts["Infer::Constants"]
|
|
219
234
|
Params["Infer::Params\nParameter type\nfrom name + default"]
|
|
220
235
|
Returns["Infer::Returns\nReturn type\nfrom method body"]
|
|
221
236
|
Raises["Infer::Raises\n@raise tags\nfrom raise/rescue"]
|
|
@@ -230,7 +245,7 @@ flowchart TB
|
|
|
230
245
|
TagPlugin["Base::TagPlugin\nOverride #call(context)\n-> Array<Tag>"]
|
|
231
246
|
CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n-> Array<Hash>"]
|
|
232
247
|
TagValue["Plugin::Tag\nStruct (name, text, types)"]
|
|
233
|
-
Context["Plugin::Context\nMethod snapshot struct"]
|
|
248
|
+
Context["Plugin::Context\nMethod snapshot struct\nnode/container/scope/\nvisibility/method/params/return/source"]
|
|
234
249
|
end
|
|
235
250
|
|
|
236
251
|
subgraph Types["External Type System"]
|
|
@@ -241,35 +256,51 @@ flowchart TB
|
|
|
241
256
|
SorbetBase["Sorbet::BaseProvider\nRBS::Prototype::RBI\nbridge"]
|
|
242
257
|
SorbetSource["Sorbet::SourceProvider\nInline sig{}\ndeclarations"]
|
|
243
258
|
SorbetRBI["Sorbet::RBIProvider\n.rbi files\ndirectories"]
|
|
259
|
+
OverloadSel["OverloadSelector"]
|
|
244
260
|
end
|
|
245
261
|
|
|
246
262
|
subgraph YardTypes["YARD Type Parser"]
|
|
247
263
|
YParser["Yard::Parser\nParse YARD type\nstrings -> AST"]
|
|
248
264
|
YFormatter["Yard::Formatter\nYARD AST ->\nRBS string"]
|
|
249
265
|
YTypes["Yard::Types\n9 AST node types\n(Named, Generic, etc.)"]
|
|
266
|
+
YRepair["Yard::Repair\nRepair whitespace-split\ntype names\n([Sym bol] -> [Symbol])\nonly known primitives"]
|
|
250
267
|
end
|
|
251
268
|
|
|
252
269
|
subgraph Server["Server / Daemon"]
|
|
253
|
-
ThinClient["exe/docscribe-client\nThin client\n· socket send/receive\n· no gem load"]
|
|
254
|
-
ServerDaemon["Server::Daemon\nSocket listener\n· check / fix / shutdown\n· JSON-RPC 2.0"]
|
|
255
|
-
Cache["Docscribe::LRUCache\nFile result cache\n(max 1000,
|
|
270
|
+
ThinClient["exe/docscribe-client\nThin client\n· socket send/receive\n· no gem load\nexcept --ensure"]
|
|
271
|
+
ServerDaemon["Server::Daemon\nSocket listener\n· check / fix / check_batch\n· update_types / ping / shutdown\n· JSON-RPC 2.0"]
|
|
272
|
+
Cache["Docscribe::LRUCache\nFile result cache\n(max 1000, key [file, strategy])\nhit = mtime== AND sig_hash=="]
|
|
256
273
|
end
|
|
257
274
|
|
|
258
275
|
Exe --> Run
|
|
259
|
-
Exe -->
|
|
276
|
+
Exe --> CLIDispatch
|
|
277
|
+
Exe --> ServerCmd
|
|
278
|
+
ServerCmd --> ServerDaemon
|
|
279
|
+
CLIDispatch --> Run
|
|
280
|
+
CLIDispatch --> InitCmd
|
|
281
|
+
CLIDispatch --> GenCmd
|
|
282
|
+
CLIDispatch --> SigsCmd
|
|
283
|
+
CLIDispatch --> RbsGenCmd
|
|
284
|
+
CLIDispatch --> ConfigDumpCmd
|
|
285
|
+
CLIDispatch --> CoverageCmd
|
|
286
|
+
CLIDispatch --> CheckCommentsCmd
|
|
260
287
|
ThinClient --> ServerDaemon
|
|
261
288
|
ServerDaemon --> ConfigClass
|
|
262
289
|
ServerDaemon --> Cache
|
|
263
290
|
ServerDaemon --> InlineRewriter
|
|
264
|
-
|
|
265
|
-
Run -->
|
|
266
|
-
Run --> GenCmd
|
|
267
|
-
Run --> SigsCmd
|
|
268
|
-
Run --> RbsGenCmd
|
|
291
|
+
Options --> Run
|
|
292
|
+
Run --> JsonFormatter
|
|
269
293
|
Run --> SarifFormatter
|
|
270
294
|
Run --> ConfigBuilder
|
|
295
|
+
Run --> UpdateTypesCmd
|
|
296
|
+
Run --> RunFork
|
|
297
|
+
RunFork --> InlineRewriter
|
|
298
|
+
ConfigDumpCmd --> ConfigClass
|
|
299
|
+
ConfigDumpCmd --> Options
|
|
300
|
+
CoverageCmd --> InlineRewriter
|
|
301
|
+
ConfigBuilder --> ValidationOverrides["validation overrides\n(validate_types,\nwarn_invalid_yard)"]
|
|
302
|
+
ValidationOverrides --> ConfigClass
|
|
271
303
|
ConfigBuilder --> ConfigClass
|
|
272
|
-
ConfigBuilder --> ServerDaemon
|
|
273
304
|
ConfigClass --> Defaults
|
|
274
305
|
ConfigClass --> Loader
|
|
275
306
|
ConfigClass --> Emit
|
|
@@ -277,6 +308,9 @@ flowchart TB
|
|
|
277
308
|
ConfigClass --> RBSConfig
|
|
278
309
|
ConfigClass --> SorbetConfig
|
|
279
310
|
ConfigClass --> PluginConfig
|
|
311
|
+
ConfigClass --> ValidateCfg
|
|
312
|
+
ConfigClass --> SortingCfg
|
|
313
|
+
ConfigClass --> TemplateCfg
|
|
280
314
|
Run --> InlineRewriter
|
|
281
315
|
InlineRewriter --> ParsingModule
|
|
282
316
|
ParsingModule --> ParserGem
|
|
@@ -287,6 +321,9 @@ flowchart TB
|
|
|
287
321
|
Registry --> CollectorPlugin
|
|
288
322
|
InlineRewriter --> DocBuilder
|
|
289
323
|
DocBuilder --> InferModule
|
|
324
|
+
DocBuilder --> ValidSvc
|
|
325
|
+
InferModule --> InferBehavior
|
|
326
|
+
InferModule --> InferConsts
|
|
290
327
|
InferModule --> Params
|
|
291
328
|
InferModule --> Returns
|
|
292
329
|
InferModule --> Raises
|
|
@@ -295,6 +332,7 @@ flowchart TB
|
|
|
295
332
|
Raises --> ASTWalk
|
|
296
333
|
Raises --> Names
|
|
297
334
|
DocBuilder --> ProviderChain
|
|
335
|
+
ProviderChain --> OverloadSel
|
|
298
336
|
ProviderChain --> SorbetSource
|
|
299
337
|
ProviderChain --> SorbetRBI
|
|
300
338
|
ProviderChain --> RBSProvider
|
|
@@ -313,15 +351,31 @@ flowchart TB
|
|
|
313
351
|
RbsGenCmd --> YParser
|
|
314
352
|
YParser --> YTypes
|
|
315
353
|
YParser --> YFormatter
|
|
354
|
+
DocBuilder --> YRepair
|
|
355
|
+
YRepair --> YParser
|
|
316
356
|
```
|
|
317
357
|
|
|
358
|
+
Source: [assets/diagrams/architecture.mmd](assets/diagrams/architecture.mmd) — GitHub renders this block directly; `bash assets/diagrams/render.sh` produces SVG for viewers without Mermaid support.
|
|
359
|
+
|
|
318
360
|
### Data flow
|
|
319
361
|
|
|
320
362
|
```mermaid
|
|
321
363
|
flowchart LR
|
|
322
364
|
subgraph Entry["Entry Points"]
|
|
323
365
|
Direct["docscribe lib\n(no --server)"]
|
|
366
|
+
Parallel["docscribe --parallel\n/ --jobs N"]
|
|
324
367
|
ViaServer["docscribe --server\nor docscribe-client"]
|
|
368
|
+
UpdateTypesFlow["update_types\ntwo-pass: aggressive → safe"]
|
|
369
|
+
end
|
|
370
|
+
|
|
371
|
+
subgraph Fork["Forked Workers (1.7.0+)"]
|
|
372
|
+
JobCount["parallel_job_count\n--jobs > DOCSCRIBE_THREADS\n> CPU count"]
|
|
373
|
+
ForkCheck{"Process.respond_to?\n(:fork)?"}
|
|
374
|
+
Warm["warm_rewrite_env\n· load gems\n· build RBS provider\n· rewrite one file"]
|
|
375
|
+
Split["split_paths\ncontiguous slices"]
|
|
376
|
+
Children["fork() per slice\ninherit warm env (COW)"]
|
|
377
|
+
Fallback["sequential\n(identical results)"]
|
|
378
|
+
Gather["merge_forked_slices\nMarshal payload over pipe\nmerge_state under mutex"]
|
|
325
379
|
end
|
|
326
380
|
|
|
327
381
|
subgraph Daemon["Server Daemon (Unix Socket)"]
|
|
@@ -331,21 +385,36 @@ flowchart LR
|
|
|
331
385
|
ApplyOverrides["apply_cli_overrides\n(reset on nil)"]
|
|
332
386
|
end
|
|
333
387
|
|
|
388
|
+
Parallel --> JobCount
|
|
389
|
+
JobCount --> ForkCheck
|
|
390
|
+
ForkCheck -->|yes| Warm
|
|
391
|
+
ForkCheck -->|no| Fallback
|
|
392
|
+
Warm --> Split
|
|
393
|
+
Split --> Children
|
|
394
|
+
Children --> Parse
|
|
395
|
+
Fallback --> Parse
|
|
396
|
+
Children --> Gather
|
|
397
|
+
Gather --> Output
|
|
334
398
|
ViaServer --> Socket
|
|
335
399
|
Socket --> ApplyOverrides
|
|
336
400
|
ApplyOverrides --> CacheCheck
|
|
337
401
|
CacheCheck -->|Hit| Socket
|
|
338
402
|
CacheCheck -->|Miss| Parse
|
|
339
403
|
Direct --> Parse
|
|
404
|
+
Entry --> UpdateTypesFlow
|
|
405
|
+
UpdateTypesFlow --> Parse
|
|
340
406
|
Parse["Parsing.parse_buffer\nParser gem / Prism"]
|
|
341
|
-
Parse --> AST["AST
|
|
407
|
+
Parse --> AST["AST"]
|
|
408
|
+
AST -.-> CommentScan["comment scan\n(buffer text)"]
|
|
342
409
|
AST --> Collect["Collector.process\n· Find methods\n· Track visibility\n· Find attr_*"]
|
|
343
410
|
AST --> CollectPlugins["CollectorPlugin#collect\n· Custom AST walks\n· Non-standard constructs"]
|
|
344
|
-
Collect --> Insertions["Insertion list\n(sorted by position)"]
|
|
411
|
+
Collect --> Insertions["Insertion list\n(sorted by position)\n(sort_by pos at dispatch)"]
|
|
345
412
|
CollectPlugins --> Insertions
|
|
346
413
|
Insertions --> Dedup["Deduplicate\n(override by position)"]
|
|
347
|
-
Dedup --> Build["DocBuilder.
|
|
348
|
-
Build
|
|
414
|
+
Dedup --> Build["DocBuilder.build\n(entry point)\nper insertion"]
|
|
415
|
+
Build -.-> RescueNote["per-method rescue:\nerror to stderr,\nrest applies"]
|
|
416
|
+
Build --> TypeGuard["warn_invalid_yard gate\n· invalid_yard_type?\n· Repair known names\n· else report invalid_type"]
|
|
417
|
+
TypeGuard --> Infer["Infer params / returns / raises\n(heuristic fallback)"]
|
|
349
418
|
Build --> SigQuery["ProviderChain\nquery external types"]
|
|
350
419
|
Build --> TagPlugins["TagPlugin#call\n(add extra @tags)"]
|
|
351
420
|
Infer --> ResultDoc["Generated YARD doc block"]
|
|
@@ -354,15 +423,78 @@ flowchart LR
|
|
|
354
423
|
ResultDoc --> Strategy{"Strategy?"}
|
|
355
424
|
Strategy -->|Safe| Merge["DocBlock.merge\npreserve + append + sort"]
|
|
356
425
|
Strategy -->|Aggressive| Replace["Replace entirely"]
|
|
357
|
-
Merge --> Rewritten["
|
|
426
|
+
Merge --> Rewritten["TreeRewriter#process\n(Parser::Source)\n-> rewritten source"]
|
|
358
427
|
Replace --> Rewritten
|
|
359
428
|
Rewritten --> Result["Result / response"]
|
|
360
429
|
Rewritten --> CacheStorage
|
|
361
430
|
CacheStorage --> Socket
|
|
362
|
-
Result
|
|
431
|
+
Result -.-> ExitCodes["exit codes:\n0 ok / 1 changes / 2 error"]
|
|
432
|
+
Children -.-> Progress["--progress\nstderr, per child"]
|
|
433
|
+
Result -->|Direct mode| Output["write-mode: file\ncheck: STDOUT summary"]
|
|
363
434
|
Result -->|Server mode| Socket
|
|
364
435
|
```
|
|
365
436
|
|
|
437
|
+
Source: [assets/diagrams/dataflow.mmd](assets/diagrams/dataflow.mmd) — regenerate with `bash assets/diagrams/render.sh`.
|
|
438
|
+
|
|
439
|
+
### IDE plugin and gem interaction
|
|
440
|
+
|
|
441
|
+
```mermaid
|
|
442
|
+
sequenceDiagram
|
|
443
|
+
autonumber
|
|
444
|
+
participant U as User / IDE
|
|
445
|
+
participant A as DocscribeAnnotator<br/>(ExternalAnnotator)
|
|
446
|
+
participant R as Runner<br/>(DocscribeDaemon)
|
|
447
|
+
participant D as Gem daemon<br/>(Unix socket, JSON-RPC 2.0)
|
|
448
|
+
participant E as Engine<br/>(InlineRewriter)
|
|
449
|
+
Note over A: open / type / save (.rb, .rake, Rakefile)
|
|
450
|
+
A ->> A: collectInformation (EDT)<br/>filters, unsaved-skip (non-RBS),<br/>configHash w/o I/O, PSI stamp
|
|
451
|
+
U ->> A: background pass
|
|
452
|
+
A ->> A: doAnnotate - generation++<br/>bgConfigHash + rbsHash(sig/**)
|
|
453
|
+
A ->> A: cache get (project, file, hash)<br/>+ stamp check
|
|
454
|
+
alt cache hit (incl. empty = clean)
|
|
455
|
+
A ->> U: apply cached / null (no gem call)
|
|
456
|
+
else cache miss
|
|
457
|
+
A ->> A: saveDocument (so daemon sees disk)
|
|
458
|
+
A ->> R: executeWithFallback(check)<br/>RunOptions(file, CHECK, json)
|
|
459
|
+
R ->> R: ensureRunning - socket alive?<br/>gem 1.5.1 or newer? ruby/SDK resolve<br/>start ruby -e (15s timeout)
|
|
460
|
+
alt daemon OK
|
|
461
|
+
R ->> D: check {file, project_dir,<br/>no_boilerplate, cli_overrides?}
|
|
462
|
+
Note over R, D: cli_overrides - rbs / rbs_collection<br/>(RbsDetector) + validate_types (setting)
|
|
463
|
+
D ->> E: rewrite_with_report (safe)
|
|
464
|
+
E ->> D: changes[] {type, line, method,<br/>message, source?}
|
|
465
|
+
D ->> R: {status ok/fail, changed, changes}
|
|
466
|
+
R ->> R: buildCheckJson to parseJson
|
|
467
|
+
else daemon down / RPC null
|
|
468
|
+
R ->> R: CLI fallback - bundle exec<br/>docscribe --format json file
|
|
469
|
+
end
|
|
470
|
+
R ->> A: RunResult(success, exit, stdout, stderr)
|
|
471
|
+
A ->> A: generation still current?<br/>else discard (null)
|
|
472
|
+
alt success is false
|
|
473
|
+
A ->> A: synthetic Docscribe/Error at 1:1<br/>do NOT cache
|
|
474
|
+
else blank stdout
|
|
475
|
+
A ->> A: empty result (legit clean, cache it)
|
|
476
|
+
else parsed
|
|
477
|
+
A ->> A: cache put (non-error only)
|
|
478
|
+
end
|
|
479
|
+
A ->> U: apply - line = findYardTagLine<br/>(at-param/at-return above def)<br/>WARNING squiggle + fix by cop<br/>Updated to UpdateTypes<br/>InvalidType to Fix YARD (local)<br/>other to safe Fix / Error no fix
|
|
480
|
+
end
|
|
481
|
+
|
|
482
|
+
Note over U, R: Quick-fix (bulb) - save to fix {strategy}<br/>or update_types {dir} (whole project)<br/>refresh + balloon. Check action -<br/>same check, balloon with counts.
|
|
483
|
+
Note over U, R: Workspace - menu to collectRubyFiles<br/>chunks of 10 to check_batch {files}<br/>aggregate balloon only (no squigglies -<br/>error files counted, not shown)
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
Source: [assets/diagrams/plugin-gem.mmd](assets/diagrams/plugin-gem.mmd) — regenerate with `bash assets/diagrams/render.sh`.
|
|
487
|
+
|
|
488
|
+
How it works, briefly: the IDE annotator collects file info on open/type/save, asks the gem daemon (`check` over Unix-socket JSON-RPC, CLI fallback), maps offenses to YARD tag lines with per-cop quick-fixes, and caches by file stamp + config hash. Daemon errors surface as file-level errors instead of silence; quick-fixes run `fix` or file-scoped `update_types`; workspace check aggregates `check_batch` into a balloon.
|
|
489
|
+
|
|
490
|
+
Version gates (plugin behavior by gem version):
|
|
491
|
+
|
|
492
|
+
| Gem version | Plugin behavior |
|
|
493
|
+
|-------------|-------------------------------------------------------------|
|
|
494
|
+
| `< 1.5.1` | always CLI, no daemon mode |
|
|
495
|
+
| `< 1.5.2` | no batch mode (workspace check scans the directory via CLI) |
|
|
496
|
+
| `< 1.6.2` | `update_types` falls back to CLI on unknown method |
|
|
497
|
+
|
|
366
498
|
## CLI
|
|
367
499
|
|
|
368
500
|
```shell
|
|
@@ -371,7 +503,7 @@ docscribe init [options]
|
|
|
371
503
|
docscribe generate [type] [name] [options]
|
|
372
504
|
docscribe sigs [options] [files...]
|
|
373
505
|
docscribe rbs [options] [files...]
|
|
374
|
-
docscribe update_types [directory]
|
|
506
|
+
docscribe update_types [directory|file] [options]
|
|
375
507
|
docscribe check_for_comments [paths...]
|
|
376
508
|
docscribe server [start|status|stop] [options]
|
|
377
509
|
```
|
|
@@ -413,8 +545,19 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
|
|
|
413
545
|
- `--progress`
|
|
414
546
|
Show progress (`[N/total] path/to/file.rb`) on stderr as each file is processed.
|
|
415
547
|
|
|
416
|
-
- `
|
|
417
|
-
|
|
548
|
+
- `--parallel`
|
|
549
|
+
Process files in parallel using forked worker processes. Each worker inherits
|
|
550
|
+
the warmed process (gems, config, RBS environment) through copy-on-write, so
|
|
551
|
+
forking skips the cold-start cost that made thread-based work slower than a
|
|
552
|
+
sequential run.
|
|
553
|
+
|
|
554
|
+
- `--jobs N`
|
|
555
|
+
Number of parallel workers (implies `--parallel`). Defaults to the number of
|
|
556
|
+
available CPUs.
|
|
557
|
+
|
|
558
|
+
- `DOCSCRIBE_THREADS` (env var)
|
|
559
|
+
Default worker count when `--jobs` is not passed. Falls back to the CPU count.
|
|
560
|
+
Set to `1` for sequential processing.
|
|
418
561
|
|
|
419
562
|
- `--quiet` (`-q`)
|
|
420
563
|
Only show status, no details (suppresses change reasons).
|
|
@@ -437,6 +580,10 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
|
|
|
437
580
|
- `--format FORMAT`
|
|
438
581
|
Output format: `text` (default, human-readable), `json` (machine-readable, RuboCop-compatible), or `sarif` (SARIF 2.1
|
|
439
582
|
JSON, compatible with GitHub Code Scanning).
|
|
583
|
+
Every JSON offense carries `cop_name`, `message`, `location`, plus machine-readable `type`
|
|
584
|
+
(`updated_return`, `missing_param`, ...) and, for type mismatches, `source` (`"rbs"`, `"infer"` or `"syntax"`).
|
|
585
|
+
Files are grouped by normalized path, so the same file passed under different spellings
|
|
586
|
+
(absolute, relative, symlinked) appears once.
|
|
440
587
|
|
|
441
588
|
- `--rbs`
|
|
442
589
|
Use RBS signatures for `@param`/`@return` when available (falls back to inference).
|
|
@@ -450,6 +597,17 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
|
|
|
450
597
|
- `--rbi-dir DIR`
|
|
451
598
|
Add an Sorbet RBI directory (repeatable). Implies `--sorbet`.
|
|
452
599
|
|
|
600
|
+
- `--[no-]validate-types`
|
|
601
|
+
Validate YARD types against inferred/RBS types and report mismatches.
|
|
602
|
+
`--no-validate-types` overrides `validate_types: true` from the config file.
|
|
603
|
+
|
|
604
|
+
- `--[no-]warn-invalid-yard`
|
|
605
|
+
Report syntactically broken YARD types such as `[Sym bol]` and apply the safe fix to
|
|
606
|
+
`[Symbol]`. Enabled by default. Independent of `--validate-types`: syntax validity does
|
|
607
|
+
not depend on inferred or external types. `--no-warn-invalid-yard` silences it and
|
|
608
|
+
leaves broken types untouched. `--no-warn-invalid-yard` overrides
|
|
609
|
+
`warn_invalid_yard: true` from the config file.
|
|
610
|
+
|
|
453
611
|
- `--include PATTERN`
|
|
454
612
|
Include PATTERN (method id or file path; glob or `/regex/`).
|
|
455
613
|
|
|
@@ -598,34 +756,43 @@ end
|
|
|
598
756
|
|
|
599
757
|
```shell
|
|
600
758
|
docscribe rbs lib
|
|
601
|
-
# Generated sig/user.rbs
|
|
759
|
+
# Generated sig/lib/user.rbs
|
|
602
760
|
```
|
|
603
761
|
|
|
604
762
|
```ruby.rbs
|
|
605
|
-
# sig/user.rbs
|
|
763
|
+
# sig/lib/user.rbs
|
|
606
764
|
class User
|
|
607
|
-
|
|
765
|
+
def initialize: (String name, Integer age) -> User
|
|
608
766
|
end
|
|
609
767
|
```
|
|
610
768
|
|
|
769
|
+
The output path mirrors the source path relative to the working directory, so `lib/user.rb`becomes `sig/lib/user.rbs` (not `sig/user.rbs`).
|
|
770
|
+
|
|
611
771
|
### `docscribe update_types` — two-pass type-aware documentation update
|
|
612
772
|
|
|
613
773
|
> [!NOTE]
|
|
614
|
-
> `docscribe update_types` is a convenience alias for the two-pass workflow above.
|
|
615
|
-
> gem
|
|
616
|
-
> `bundle exec rbs collection install
|
|
617
|
-
> missing, types will fall back to AST inference.
|
|
774
|
+
> `docscribe update_types` is a convenience alias for the two-pass workflow above. RBS features require Ruby 3.0+ and
|
|
775
|
+
> the `rbs` gem; pass `--no-rbs` to skip them. If `rbs.collection: true` is set in `docscribe.yml`, the collection is
|
|
776
|
+
> discovered automatically (otherwise run `bundle exec rbs collection install` first). Type accuracy depends on your
|
|
777
|
+
> RBS signatures — if signatures are incomplete or missing, types will fall back to AST inference.
|
|
618
778
|
|
|
619
|
-
`docscribe update_types` runs two passes to bring both docs and RBS signatures up to date
|
|
779
|
+
`docscribe update_types` runs two passes to bring both docs and RBS signatures up to date. The target can be a
|
|
780
|
+
directory **or a single file** (handy for IDE quick-fixes — only that file is touched):
|
|
620
781
|
|
|
621
782
|
1. **Pass 1** — `docscribe -AkB --rbs-collection <dir>`: aggressively rebuilds doc blocks, preserves existing
|
|
622
783
|
descriptions, suppresses boilerplate, uses RBS collection types.
|
|
623
784
|
2. **Pass 2** — `docscribe -aB --rbs-collection <dir>`: safe merge cleanup with no boilerplate.
|
|
624
785
|
|
|
786
|
+
Extra flags (`--rbs`, `--sig-dir DIR` (repeatable), `--rbs-collection`, `--[no-]validate-types`, `--no-rbs`) are
|
|
787
|
+
passed through to both passes.
|
|
788
|
+
|
|
625
789
|
```shell
|
|
626
790
|
# Update docs in lib/ using RBS collection
|
|
627
791
|
docscribe update_types lib
|
|
628
792
|
|
|
793
|
+
# Update a single file only
|
|
794
|
+
docscribe update_types lib/user.rb
|
|
795
|
+
|
|
629
796
|
# Defaults to current directory
|
|
630
797
|
docscribe update_types
|
|
631
798
|
```
|
|
@@ -659,17 +826,22 @@ about your project and writes a tailored configuration.
|
|
|
659
826
|
# Create docscribe.yml interactively
|
|
660
827
|
docscribe init
|
|
661
828
|
|
|
662
|
-
#
|
|
663
|
-
docscribe init --
|
|
829
|
+
# Write the default config without prompting
|
|
830
|
+
docscribe init --force
|
|
831
|
+
|
|
832
|
+
# Print the template to stdout instead of writing a file
|
|
833
|
+
docscribe init --stdout
|
|
664
834
|
```
|
|
665
835
|
|
|
666
836
|
**Flags:**
|
|
667
837
|
|
|
838
|
+
- `--config PATH` — where to write the config (default: `docscribe.yml`).
|
|
839
|
+
- `-f`, `--force` — overwrite if the file already exists.
|
|
840
|
+
- `--stdout` — print the config template to stdout instead of writing a file.
|
|
668
841
|
- `--pre-commit` — generate and install a Git pre-commit hook that checks documentation on staged `.rb` files using
|
|
669
842
|
`docscribe --verbose`. The hook exits with a warning if staged files lack documentation.
|
|
670
843
|
- `--pre-commit --uninstall` — remove the pre-commit hook.
|
|
671
844
|
- `--pre-commit --dry-run` — preview the hook script without installing.
|
|
672
|
-
- `--default` — skip interactive prompts, write default config.
|
|
673
845
|
- `-h`, `--help` — show help.
|
|
674
846
|
|
|
675
847
|
### `docscribe config` — view resolved configuration
|
|
@@ -805,13 +977,17 @@ The daemon speaks JSON-RPC 2.0 over Unix socket. Each request is a JSON line, ea
|
|
|
805
977
|
|
|
806
978
|
Methods:
|
|
807
979
|
|
|
808
|
-
| Method
|
|
809
|
-
|
|
810
|
-
| `check`
|
|
811
|
-
| `fix`
|
|
812
|
-
| `check_batch`
|
|
813
|
-
| `
|
|
814
|
-
| `
|
|
980
|
+
| Method | Parameters | Result |
|
|
981
|
+
|----------------|-------------------------------------------------------------------------------------|---------------------------------------------------------|
|
|
982
|
+
| `check` | `file` (string), `strategy` ("safe"/"aggressive"), `cli_overrides` (hash, optional) | `status`, `changed`, `changes` |
|
|
983
|
+
| `fix` | same as `check` | `status`, `changed`, `changes` |
|
|
984
|
+
| `check_batch` | `files` (array of strings), `strategy`, `cli_overrides`, `timeout` (int, optional) | array of per-file results |
|
|
985
|
+
| `update_types` | `file` (string, optional), `dir` (string, optional; `file` wins) | `status`, `changed`, `changes` |
|
|
986
|
+
| `ping` | — | `version`, `pid`, `socket_path`, `started_at`, `uptime` |
|
|
987
|
+
| `shutdown` | — | `status` |
|
|
988
|
+
|
|
989
|
+
Each entry in `changes` carries `type`, `line`, `message` and, for type mismatches, `source` (`"rbs"`, `"infer"` or
|
|
990
|
+
`"syntax"`) plus `param` where applicable — IDE plugins use `source` to pick the right fix (RBS update vs YARD fix).
|
|
815
991
|
|
|
816
992
|
Error codes (standardized for IDE plugin integration):
|
|
817
993
|
|
|
@@ -906,7 +1082,8 @@ In write modes:
|
|
|
906
1082
|
|
|
907
1083
|
> [!IMPORTANT]
|
|
908
1084
|
> The `M` marker only appears when `--rbs` or `--sorbet` is enabled, since type mismatches are detected by
|
|
909
|
-
> comparing external signatures against inferred types.
|
|
1085
|
+
> comparing external signatures against inferred types. It also requires `--no-validate-types`: with
|
|
1086
|
+
> `validate_types` on (the default) a signature mismatch is reported as a fixable difference (`F`), not as `M`.
|
|
910
1087
|
|
|
911
1088
|
With `--verbose`, Docscribe prints per-file statuses instead; type mismatches show as `MT` with the specific difference.
|
|
912
1089
|
|
|
@@ -931,11 +1108,12 @@ Useful flag combinations for common workflows:
|
|
|
931
1108
|
projects.
|
|
932
1109
|
- `docscribe -a --sorbet --rbi-dir sorbet/rbi lib` — safe autocorrect using Sorbet RBI signatures.
|
|
933
1110
|
- `docscribe update_types lib` — two-pass type-aware update: aggressively rebuilds docs with kept descriptions and RBS
|
|
934
|
-
collection, then safe-merges to clean up.
|
|
1111
|
+
collection, then safe-merges to clean up. Accepts a single file too: `docscribe update_types lib/user.rb`.
|
|
935
1112
|
See [docscribe update_types](#docscribe-update_types--two-pass-type-aware-documentation-update).
|
|
936
1113
|
|
|
937
1114
|
> [!NOTE]
|
|
938
|
-
> `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood
|
|
1115
|
+
> `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood
|
|
1116
|
+
> (or `rbs.collection: true` from the config — then no flag is needed).
|
|
939
1117
|
> If your RBS signatures are incomplete, types may fall back to AST inference.
|
|
940
1118
|
|
|
941
1119
|
## Parser backend (Parser gem vs Prism)
|
|
@@ -1045,7 +1223,8 @@ class Demo
|
|
|
1045
1223
|
end
|
|
1046
1224
|
```
|
|
1047
1225
|
|
|
1048
|
-
Generated docs will prefer the RBS signature over inferred Ruby types:
|
|
1226
|
+
Generated docs will prefer the RBS signature over inferred Ruby types (`emit.header: true`
|
|
1227
|
+
in the example below adds the `+#foo+ -> ...` header line; it is off by default):
|
|
1049
1228
|
|
|
1050
1229
|
```ruby
|
|
1051
1230
|
class Demo
|
|
@@ -1096,6 +1275,13 @@ You can combine `--rbs-collection` with `--sig-dir` to mix gem signatures with y
|
|
|
1096
1275
|
docscribe -a --rbs-collection --sig-dir sig lib
|
|
1097
1276
|
```
|
|
1098
1277
|
|
|
1278
|
+
If `rbs.collection: true` is set in `docscribe.yml`, the collection is discovered automatically and the flag
|
|
1279
|
+
can be omitted everywhere (including plain `check` and the daemon):
|
|
1280
|
+
|
|
1281
|
+
```shell
|
|
1282
|
+
docscribe -a lib
|
|
1283
|
+
```
|
|
1284
|
+
|
|
1099
1285
|
> [!NOTE]
|
|
1100
1286
|
> `--rbs-collection` only improves types for methods defined in gems that ship RBS
|
|
1101
1287
|
> signatures. For your own classes, provide a `sig/` directory with hand-written or
|
|
@@ -1155,7 +1341,8 @@ class Demo
|
|
|
1155
1341
|
end
|
|
1156
1342
|
```
|
|
1157
1343
|
|
|
1158
|
-
Docscribe will use the Sorbet signature instead of the inferred body type:
|
|
1344
|
+
Docscribe will use the Sorbet signature instead of the inferred body type (`emit.header: true`, off by default, adds the
|
|
1345
|
+
header line):
|
|
1159
1346
|
|
|
1160
1347
|
```ruby
|
|
1161
1348
|
class Demo
|
|
@@ -1228,7 +1415,7 @@ class Demo
|
|
|
1228
1415
|
end
|
|
1229
1416
|
```
|
|
1230
1417
|
|
|
1231
|
-
Example output:
|
|
1418
|
+
Example output (with `emit.header: true`; off by default):
|
|
1232
1419
|
|
|
1233
1420
|
```ruby
|
|
1234
1421
|
# demo.rb
|
|
@@ -1301,7 +1488,7 @@ Heuristics (best-effort).
|
|
|
1301
1488
|
Parameters:
|
|
1302
1489
|
|
|
1303
1490
|
- `*args` -> `Array`
|
|
1304
|
-
- `**kwargs` -> `Hash`
|
|
1491
|
+
- `**kwargs` -> `Hash[Symbol, untyped]` with RBS, `Hash<Symbol, Object>` in YARD, bare `Hash` from pure inference
|
|
1305
1492
|
- `&block` -> `Proc`
|
|
1306
1493
|
- keyword args:
|
|
1307
1494
|
- `verbose: true` -> `Boolean`
|
|
@@ -1316,6 +1503,18 @@ Return values:
|
|
|
1316
1503
|
- For simple bodies, Docscribe looks at the last expression or explicit `return`.
|
|
1317
1504
|
- Unions with `nil` become optional types (e.g. `String` or `nil` -> `String?`).
|
|
1318
1505
|
- For control flow (`if`/`case`), it unifies branches conservatively.
|
|
1506
|
+
- Blocks resolve to generics where possible: `map`/`then` over known elements give `Array<String>` instead of
|
|
1507
|
+
bare `Array`; `arr << x` and `x += 1` resolve through RBS (`self`-returns stay `self`); `&.`/`||`/`()` receivers
|
|
1508
|
+
are unwrapped before lookup; `each_with_index` chains infer `Enumerator`/`Hash` element types
|
|
1509
|
+
(`arr.each_with_index.to_h { |x, i| [k, v] }` infers `Hash<K, V>` from the pair literal;
|
|
1510
|
+
the second block parameter is always the `Integer` index).
|
|
1511
|
+
- Generic compatibility is structural, not textual: `Hash` matches `Hash<Symbol, Config>`, `Array` matches
|
|
1512
|
+
`Array<String>`, `String?` equals `String, nil` and `String|nil`, and `String` is accepted where `Object` is
|
|
1513
|
+
expected. YARD `[]` and RBS `<>` (plus `untyped`/`Object`) are normalized before comparison.
|
|
1514
|
+
- `void` understands Ruby idioms: initializers and `setup` may return `Hash`/`self`/`Boolean`, predicates
|
|
1515
|
+
(`valid?`) may return `Boolean`.
|
|
1516
|
+
- One crashing method never blanks the whole file: the error goes to stderr (`Docscribe: skipping method foo ...`)
|
|
1517
|
+
and the remaining methods are still processed.
|
|
1319
1518
|
|
|
1320
1519
|
> [!TIP]
|
|
1321
1520
|
> Docscribe resolves return types for core Ruby methods (`Integer#positive?`, `String#upcase`, etc.)
|
|
@@ -1340,6 +1539,9 @@ Docscribe detects exceptions and rescue branches:
|
|
|
1340
1539
|
|
|
1341
1540
|
- Conditional return types for rescue branches:
|
|
1342
1541
|
- Docscribe adds `@return [Type] if ExceptionA, ExceptionB` for each rescue clause
|
|
1542
|
+
- Conditional tags never overwrite the main `@return` type, so `check` and `update_types` agree with each other
|
|
1543
|
+
(no ping-pong between runs). Rescue bodies referencing constants resolve to the constant's value type when
|
|
1544
|
+
the constant is visible from the method's scope.
|
|
1343
1545
|
|
|
1344
1546
|
## Visibility semantics
|
|
1345
1547
|
|
|
@@ -1562,7 +1764,9 @@ plugins:
|
|
|
1562
1764
|
- ./docscribe_plugins
|
|
1563
1765
|
```
|
|
1564
1766
|
|
|
1565
|
-
Each entry is passed to `require`.
|
|
1767
|
+
Each entry is passed to `require`. A relative path is expanded from the directory holding
|
|
1768
|
+
`docscribe.yml` (not from the current working directory), so the plugin resolves the same way
|
|
1769
|
+
no matter where you invoke `docscribe` from.
|
|
1566
1770
|
|
|
1567
1771
|
Duck typing is also supported — any object responding to `#call` is treated as a `TagPlugin`, any object responding to
|
|
1568
1772
|
`#collect` is treated as a `CollectorPlugin`:
|
|
@@ -1685,7 +1889,7 @@ docscribe --exclude-file '/^spec\//' lib
|
|
|
1685
1889
|
|
|
1686
1890
|
> [!NOTE]
|
|
1687
1891
|
> `/regex/` passed to `--include`/`--exclude` is treated as a **method-id** pattern. Use `--include-file` /
|
|
1688
|
-
`--exclude-file` for file regex filters.
|
|
1892
|
+
> `--exclude-file` for file regex filters.
|
|
1689
1893
|
|
|
1690
1894
|
Enable attribute-style documentation generation with:
|
|
1691
1895
|
|
|
@@ -1883,12 +2087,14 @@ The generated file contains:
|
|
|
1883
2087
|
### Full configuration reference
|
|
1884
2088
|
|
|
1885
2089
|
<details>
|
|
1886
|
-
<summary>Click to expand —
|
|
2090
|
+
<summary>Click to expand — 44 config keys</summary>
|
|
1887
2091
|
|
|
1888
2092
|
| Key | Type | Default | Description |
|
|
1889
2093
|
|-------------------------------------------|------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
|
|
1890
2094
|
| `keep_descriptions` | `bool` | `false` | Preserve existing doc text in aggressive mode |
|
|
1891
2095
|
| `skip_anonymous_block_params` | `bool` | `false` | Skip `@param [Proc] block` for anonymous `&` params |
|
|
2096
|
+
| `validate_types` | `bool` | `true` | Validate YARD types against inferred/RBS types and report mismatches |
|
|
2097
|
+
| `warn_invalid_yard` | `bool` | `true` | Report syntactically broken YARD types (e.g. `[Sym bol]`) |
|
|
1892
2098
|
| `emit.header` | `bool` | `false` | Generate method header line (`+#foo+ -> ...`) |
|
|
1893
2099
|
| `emit.include_default_message` | `bool` | `true` | Insert default message (`Method documentation.`) |
|
|
1894
2100
|
| `emit.include_param_documentation` | `bool` | `true` | Insert param description text (`Param documentation.`) |
|
|
@@ -1998,6 +2204,7 @@ yard doc -o docs
|
|
|
1998
2204
|
- Safe mode only merges into existing **doc-like** comment blocks. Ordinary comments that are not recognized as
|
|
1999
2205
|
documentation are preserved and treated conservatively.
|
|
2000
2206
|
- Type inference is heuristic. Complex flows and meta-programming will fall back to `Object` or best-effort types.
|
|
2207
|
+
- A method that crashes documentation generation is skipped with a stderr warning instead of failing the whole file.
|
|
2001
2208
|
- Aggressive mode (`-A`) replaces existing doc blocks and should be reviewed carefully.
|
|
2002
2209
|
|
|
2003
2210
|
## Roadmap
|