question/possible issue - inconsistent references to how to invoke the commands in README

[heckj]

I was working through the README here to try out swift-doc, and noticed that it's referenced two different ways - not entirely sure which was correct or if they're explicitly the same. One is swift-doc cmd... and the other is swift doc cmd... (without the hyphen between swift and doc).

I didn't know if you'd done something to extend the "swift" toolchain such that this command would fit in naturally, or if someone was simply knocking out a README quickly and typo'd missing the hyphens in the command. In either case, the equivalency would be usefult to call out if it exists - and the README references made more consistent.

I'm happy to create a pull request to clean things up, but I wanted to ask first what "was the intended way" before I made any of my own assumptions.

[MaxDesiatov]

The swift driver passes its commands to another executable with an appropriate name like swift-<command>. You can check that by running swift blah in your terminal, it will complain about not being able to find swift-blah executable (I'd be surprised if you actually have an executable with such name in your PATH 🙂). Because of this, swift-doc and swift doc invocations are equivalent from a user perspective. If there's a difference, I don't know of any and it probably would be an obscure edge case a random user would be unlikely to stumble upon, in my opinion.

[mattt]

@MaxDesiatov Couldn't have said it better myself!

@heckj The intention is for swift-doc to be run as a subcommand of swift. The use of swift-doc in documentation should be limited to denoting the command itself, outside of any usage context.

However, even though swift-doc and swift doc are equivalent, the ambiguity is conspicuous and worth documenting. I submitted #89 to do just that.

[heckj]

Got it - thank you!