@jonpryor: ping for review, when you get a chance? :)

You must now add the -classic parameter when running mdoc update for a set of classic assemblies.

I'm not fond of this idea, in large part because I have no idea what it means regarding backward compatibility.

How do I know if I have a "classic" assembly? How do I know that I don't have one?

My concern is that I and others have existing Makefiles which use mdoc update and various other commands. Will they be broken?

Based on the patch itself, I think it might make more sense to use -api-style=STYLE, where STYLE is classic, or unified, or...anything else! I think this might make more sense; it would also start getting "specifics" out of the codebase like isClassicRun or AssemblyInfo[not(@apistyle) or @apistyle='classic'] and replace it with specific epistyle checks which are controllable by the mdoc runner.

Well, all of this functionality, truth be told, was added to support a singular product, which is Xamarin's iOS assemblies ... so from a backwards compatibility perspective, there is only one "client" of this feature, and I've adjusted that makefile accordingly (that PR internally is waiting for this PR).

Now, in the context of the feature itself, this is all predicated on the fact that a namespace prefix is being dropped ... so in the case of iOS, MonoTouch. So mdoc infers that it is operating on the unified assemblies when it sees the dropns parameter. Previously, there were no logical differences between processing classic assemblies vs a run of the mill everyday mdoc update against a normal standalone assembly. However, that was all based on an assumption that all types and members would be replicated in both classic and unified, which is incorrect. So in order to let the logic differ when processing a classic assembly, I had to be able to explicitly state as such on the command line.

Right now, there is too much internal logic that depends on the apistyle to be a binary distinction ... it's either unified, or classic, so making the change for a runner-configurable apistyle would be way too much work. However, you make a good point about backwards compatibility, and I can at a minimum make the CLI syntax work for the future.

I'm going to change it as you suggest, so that there's an api-style parameter ... but for the time being, will limit it so that the only two valid values are classic, and unified. That way, in the future, we can disentangle the logic without affecting build scripts.

@jonpryor ok, I've made some small changes so that instead of -classic, we simply use --api-style=classic and --api-style=unified. Of course, that will require changes to the existing invocation, but as I mentioned I'm taking care of that in the project where this is being used ... and also is reflected in all the tests.

Additionally ... like you mention, this opens up future extensibility of this feature so that the api style value can be controlled from the command line :)

LGTM, aside from the previously mentioned code formatting.

@jonpryor I made the requested style change to add the tab stop. When this commit gets merged, I'll go ahead and rebase #2377 to include the change, at which point it will be ready to go and pass all tests :)

Thanks!