<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto">Hi Jon,<div><br></div><div>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”.</div><div><br></div><div>I agree with Erica on the point though that documentation with code is actually helpful <i>to me </i>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.</div><div><br></div><div>I really would like some work on Xcode though to allow hiding documentation, and improvements to the generated interfaces which are somewhat lacking atm.</div><div><br></div><div><div>- Rod</div><div><div></div><div><br>On 9 Nov 2017, at 5:57 am, Erica Sadun via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br><br></div><blockquote type="cite"><div><span>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.</span><br><span></span><br><span>-- E</span><br><span></span><br><span></span><br><blockquote type="cite"><span>On Nov 8, 2017, at 11:20 AM, Jon Gilbert via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>When I go to look at the actual source code of something, it’s almost always because:</span><br></blockquote><blockquote type="cite"><span>(a) the documentation was insufficient for me to really understand what’s going on, or</span><br></blockquote><blockquote type="cite"><span>(b) I already know what’s happening but I just want set a breakpoint for debugging.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>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. </span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>In ObjectiveC we could mostly get around this by putting docs in the headers. But Swift doesn’t have headers.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>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. </span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>Is this a pipe dream or could it someday happen? </span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>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.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>That way, you can keep comments to a minimum in your source files.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>Thoughts?</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>(If this has been pitched before, slap me please, but I didn’t see it.)</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>- Jon</span><br></blockquote><blockquote type="cite"><span>_______________________________________________</span><br></blockquote><blockquote type="cite"><span>swift-evolution mailing list</span><br></blockquote><blockquote type="cite"><span><a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a></span><br></blockquote><blockquote type="cite"><span><a href="https://lists.swift.org/mailman/listinfo/swift-evolution">https://lists.swift.org/mailman/listinfo/swift-evolution</a></span><br></blockquote><span></span><br><span>_______________________________________________</span><br><span>swift-evolution mailing list</span><br><span><a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a></span><br><span><a href="https://lists.swift.org/mailman/listinfo/swift-evolution">https://lists.swift.org/mailman/listinfo/swift-evolution</a></span><br></div></blockquote></div></div></body></html>