[swift-evolution] [Pitch] .swiftDoc files instead of inline docs

[Jon Gilbert]

When I go to look at the actual source code of something, it’s almost always because:
(a) the documentation was insufficient for me to really understand what’s going on, or
(b) I already know what’s happening but I just want set a breakpoint for debugging.

In both of these cases, the presence of huge amounts of inline documentation in the source files just makes the code very difficult to read. 

In ObjectiveC we could mostly get around this by putting docs in the headers. But Swift doesn’t have headers.

So I find myself wishing I could keep documentation in a separate file, perhaps a file that even takes advantage of XCode 9’s new built-in Markdown formatting. 

Is this a pipe dream or could it someday happen? 

I could even imagine a future in which the leading Swift IDEs can show you a split screen view in which the documentation for a function automatically appears in an *editable* side bar, and when you edit it there, the .swiftDoc file gets updated as well, but your code itself remains pure.

That way, you can keep comments to a minimum in your source files.

Thoughts?

(If this has been pitched before, slap me please, but I didn’t see it.)

- Jon