Feature idea: file-level filtering option

Summary

Add a CLI option to only doc-test source files containing a special comment or YARD tag.

This would allow for gradual file-by-file incorporation into existing code bases that already have @example tags all over the place that were not written to doc-test.

Like how Flow uses // @flow comments to activate type checking at a file level, if you happen to have used that. I swear I've seen this sort of thing in other softwares as well, but they're not coming to mind at the moment.

Usage

Add comments or tags to the desired file and add a flag to the CLI command, something like:

yard doctest --opt-in

I'm not sure about the name --opt-in, but I'm having trouble thinking of something better right now.

Background

I'm doing this right now by sticking a

# doctest: true

comment in the files that I've migrated over to use doc-tests, then running via a harness script

bundle exec \
  yard doctest $@ \
    $(rg --files-with-matches '# doctest: true' --glob='*.rb' ./lib/)

However, I think it would ease adoption into existing code bases to have this functionality built-in. And I'd like to see more adoption, 'cause I feel there is little more frustrating than wasting precious time with new software in "what the hell am I doing wrong?"-land only to eventually figure out that the example itself is broken.

Implementation Thoughts

Ruby already has "magic" file-level comments like # frozen_string_literal: true, etc., so there's some basis for the # doctest: true approach, though it might be confusing since the other magic comments people are used to seeing are Ruby VM directives, and this is not. But magic comments are also used to tell editors things about the file and such, so it seems reasonable. Maybe # yard-doctest: true would be more clear.

Using a YARD tag is possibly another option, like @doctest true, but it's a least a bit more complicated... I'm not familiar how (if at all) YARD binds file-level doc-strings as I've only ever used "code-object"-level stuff.

A YARD tag could be naturally be extended to finer granularity: putting @doctest true or @doctest false on method docs to switch those on or off individually.