Document why a user should choose the source or reflect mode

[13rac1]

Requested feature

Document why a user should choose the source or reflect mode.

Why the feature is needed

The README states:

mockgen has two modes of operation: source and reflect. Source mode generates mock interfaces from a source file. Reflect mode generates mock interfaces by building a program that uses reflection to understand interfaces.

The CLI help states:

mockgen has two modes of operation: source and reflect.

Source mode generates mock interfaces from a source file. It is enabled by using the -source flag. Other flags that may be useful in this mode are -imports and -aux_files. Example: mockgen -source=foo.go [other options]

Reflect mode generates mock interfaces by building a program that uses reflection to understand interfaces. It is enabled by passing two non-flag arguments: an import path, and a comma-separated list of symbols.

Neither explains which mode a user should choose. Is one faster than the other? Is one more reliable? Are they the same? If so, why do both exist?

This is a follow up issue as requested in https://github.com/golang/mock/issues/36#issuecomment-574470101

[codyoss]

Thanks for opening this issue, I agree this is something that should be addressed. I would like to leave this issue open a bit to collect user experiences. I know there are some edge cases out there that force people into one or the other, and honestly I don't know them all. If you have specific cases you have found please share!

Also, I would like to know these difference so that in the future we can blur the lines and the cli just works. I would love to deprecate the need for some of the flags too eventually. Thanks for the report.

[codyoss]

One difference is how type aliases are handled, works correct in source mode: https://github.com/golang/mock/issues/244

[codyoss]

mocking unexported interfaces requires source mode: #297

[linzhp]

At Uber, we call mockgen from bazel_gomock, this is what we found besides what @codyoss said above:

• source mode is very slow mainly due to packages.Load call with default goListDriver (https://github.com/bazelbuild/rules_go/issues/2366). #420 improves it
• The output of mockgen -prog_only is compiled and linked in bazel_gomock, leading to a very big executable because it links the whole transitive dependency closure of the mocked package. The Go linker is quite slow, and the large executable makes remote cache inefficient. In alternative way to get the type information is to have a small program read .a files using golang.org/x/tools/go/gcexportdata

• 244 makes Bazel rule generation in reflect mode very hard

[kishaningithub]

We use source mode for interfaces in our repository and reflect mode for interfaces in dependencies.

[Tatskaari]

We've migrated from src to reflection in Please for a couple of reasons:

1) Source mode seemed to have a hard time understanding our code structure. We don't set a go path or use modules, we use -importcfg to tell go tool compile etc. where to find packages. I'm not convinced this should be a problem though... ideally mockgen could just parse the srcs without needing to understand how imports work. 2) Reflect mode worked better when mocking gRPC interfaces because we can specify which interfaces to mock. Mocking everything lead to some obtuse failures for some internal interface in the gRPC generated code.