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

[Jeff Biggus]

I agree with Jon that conflating docs with code makes an otherwise clean swift file into a bit of a mess, and it discourages me slightly from properly documenting.

If there was something akin to "extension" but for adding documentation from a separate file ("doc Class {...}"), that could be great. For me it would make maintaining easier, as I could have the doc file open in one window, where I scroll through independently and see several function docs near each other, and my clean code in another.

Code files would benefit from less cognitive overload when wading through them. Doc syntax is its own thing. If desired, Xcode could certainly warn against obvious mismatches that might happen as the code evolves.

My 2¢,
jeff 


> On Nov 8, 2017, at 12:20 PM, 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