[ffigen] Clarify docs for include/exclude rules

[stuartmorgan]

I'm trying to temporarily work around https://github.com/dart-lang/native/issues/1416 by excluding the classes that have the type problem, since I don't currently need them. I updated my config to:

exclude-all-by-default: true
objc-interfaces:
  include:
    - 'AVAudioSession'
    - 'AVPlayer'
    - 'FVPVideoPlayer'
  exclude:
    # Due to https://github.com/dart-lang/native/issues/1416
    - 'AVComposition'
    - 'AVFragmentedAsset'
    - 'AVFragmentedMovie'
    - 'AVMovie'
    - 'AVMutableComposition'
    - 'AVMutableMovie'

But the generated output still has those classes in it, so still doesn't compile. The README for ffigen says:

Note: exclude overrides include.

so I would expect this to prevent the classes from being generated. It's not clear to me why it's not.

[liamappelbe]

The include/exclude rules never prevent transitive deps from being pulled in, even if you explicitly exclude them. What the docs mean is that you can include using a broad regex like ".*", then exclude specific names from that regex. We should definitely clarify the docs.

I'm hesitant to filter transitive deps, because in general it's not clear how to handle it. In this specific case it makes intuitive sense to omit any methods that receive or return an ObjC interface that you've explicitly excluded. But for other cases it's not so easy to cut out a transitive dep on an ObjC interface (super types, struct members, block signatures, etc). There's also the question of whether/how this explicit exclusion logic would work for other entities that can be transitive deps (structs, unions, enums, etc). So we'd end up with special cased exclusion logic that only applies when an ObjC interface is a transitive dep only due to being used in a method on another ObjC interface.

So I think this specific case should be handled by method filtering instead.

[stuartmorgan]

So I think this specific case should be handled by method filtering instead.

Yes, method filtering would definitely address both the specific use case of needing to exclude these methods for now, and more generally serve as a way of cutting down transitive dependencies in a way that has clean cut points.