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

[Erica Sadun]

Colocation of docs with the material they document is valuable to me and I presume anyone updating code. If anything, it would be nice if Xcode provided a show/hide doc headers toggle though.

-- E


> On Nov 8, 2017, at 11:20 AM, Jon Gilbert via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 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
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution