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 helpful to me and I would probably prefer documentation around methods and types to sit with the content itself. I also find documentation really helpful in breaking up a swift file, away from being code soup, and into a very formalised structure that I find easier to cognitively parse. I really would like some work on Xcode though to allow hiding documentation, and improvements to the generated interfaces which are somewhat lacking atm. - Rod > On 9 Nov 2017, at 5:57 am, Erica Sadun via swift-evolution > <swift-evolution@swift.org> 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. > > -- E > > >> On Nov 8, 2017, at 11:20 AM, Jon Gilbert via swift-evolution >> <swift-evolution@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@swift.org >> https://lists.swift.org/mailman/listinfo/swift-evolution > > _______________________________________________ > swift-evolution mailing list > swift-evolution@swift.org > https://lists.swift.org/mailman/listinfo/swift-evolution
_______________________________________________ swift-evolution mailing list swift-evolution@swift.org https://lists.swift.org/mailman/listinfo/swift-evolution
