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

To those who pointed out that XCode can already fold comment blocks, let me point out that only works in XCode, and not in, say, github. If my pitch were implemented, your IDE could still show you the documentation inline with the code. In fact, XCode already lets you option-click a function

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

They removed the little UI sidebar that was so useful for code folding, though. I do hope it makes a return. Also I am not saying projects should be forced to keep docs in separate files, just that it would be nice to have the option. I suppose it could be achieved through an XCode plugin

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

> On 8 Nov 2017, at 18:57, Erica Sadun wrote: > > 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. [Xcode 9.1] Editor > Code Folding > Fold

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

Hi Jon, An interesting proposal. I see value in an external markdown-formatted document to compliment our Swift code, but currently I already do this when discussing ideas or architecture and just call it “.md”. I agree with Erica on the point though that documentation with code is actually

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

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

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

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] [Pitch] .swiftDoc files instead of inline docs

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