<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div><span style="background-color: rgba(255, 255, 255, 0);">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. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">If my pitch were implemented, your IDE could still show you the documentation inline with the code. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">In fact, XCode already lets you option-click a function call to see a pop-up that contains the documentation (which currently comes from the doc comments but could easily come from a .swiftDoc file). XCode can also already show you the documentation in the help sidebar. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">So why not go a step further and have all documentation in a separate file, then have the IDE be able to make it appear as if it were inline, but without it affecting the line numbers of code?</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">As well, you could have PR rules that permit .swiftDoc-only commits with fewer required code reviewers. The IDE could require that any new .swift file to be accompanied by a .swiftDoc file. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">During code review, empty .swiftDoc commits, or commits that substantially change a .swift file without changing the associated .swiftDoc file, would stand out like a sore thumb during code review, helping to prevent documentation getting out of sync. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">As well, since the swiftDoc file could now be analyzed according to its own grammar, the compiler could even auto-generate the basic docs for any new function and throw warnings for any undocumented functions, arguments, vars, etc. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">The live Markdown capabilities already in XCode means that users could be prevented from incorrect Markdown by compiler errors/warnings. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">As well, when you’re browsing a repo in github, it would be trivial to open a second browser tab (or split view, thanks to the latest OSs) with the accompanying .swiftDoc markdown file (which github would auto-format, making it much more legible!). It’s easy to use command-f to jump to the declaration you are interested in, and XCode could of course jump you to it.</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">Currently there is nothing to prevent doc comments from getting out of sync with the code they are supposed to document, however with a .swiftDoc file I believe it would be easier for the compiler to make sure every function’s documentation at least has the correct labels for each argument, and include such changes into refactors.</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">This feature would be fully optional for folks who want to keep documentation in-line, or don’t have time to migrate existing projects. Of course, imagine if XCode could migrate your projects for you? :D</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">One last thing: using separate files for documentation would allow for comments to be in multiple languages. There are multiple ways this could be approached. One way would be for the .swiftDoc files that are in the same folder with your source to be in default language for the project (assuming English), and then the translated docs are kept in subfolders. Or, the translations could all just be in different parts of the same file, or they could all be kept in folders. </span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">I know project maintainers likely don’t want to think about “oh god the idea of maintaining multiple languages of documentation”, but some projects already have to do this, and for them, this might be a godsend, since the compiler would know if the files got out of sync. </span>Also, it might be nice to refer to the docs in the native language of the project, when it’s not English, and the broken-English documentation makes no sense.</div><div><br></div><div>In the future (or even now), having docs in separate files could also make it much simpler to create an auto-translator, since the parts of a swiftDoc that refer to actual code could be in backticks, forcing monospace and preventing translation. m</div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">In conclusion, I believe in the single responsibility principle. Making a .swift file contain two entirely different syntaxes of code (Swift and Markdown) seems like a violation of this. Having small comments and //MARK: - to help someone reading code is great, but huge paragraphs and lists of full documentation often requires more room than the code itself, so what am I looking at? Code or documentation? Both? It’s just bad design.</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">I’m just saying. :D</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">- Jon</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><blockquote type="cite" __apple_fixed_attribute="true"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br>On Nov 8, 2017, at 12:59, Rod Brown <<a href="mailto:rodney.brown6@icloud.com">rodney.brown6@icloud.com</a>> wrote:<br><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Hi Jon,</span></font><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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”.</span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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.</span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">I really would like some work on Xcode though to allow hiding documentation, and improvements to the generated interfaces which are somewhat lacking atm.</span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></div><div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">- Rod</span></font></div><div><div></div><blockquote type="cite" __apple_fixed_attribute="true"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><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></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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.<br><br>-- E<br><br><br></span></font><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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:<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">When I go to look at the actual source code of something, it’s almost always because:<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">(a) the documentation was insufficient for me to really understand what’s going on, or<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">(b) I already know what’s happening but I just want set a breakpoint for debugging.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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. <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">In ObjectiveC we could mostly get around this by putting docs in the headers. But Swift doesn’t have headers.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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. <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Is this a pipe dream or could it someday happen? <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">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.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">That way, you can keep comments to a minimum in your source files.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Thoughts?<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">(If this has been pitched before, slap me please, but I didn’t see it.)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">- Jon<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">_______________________________________________<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">swift-evolution mailing list<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><a href="https://lists.swift.org/mailman/listinfo/swift-evolution">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br></span></font></blockquote><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br>_______________________________________________<br>swift-evolution mailing list<br><a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br><a href="https://lists.swift.org/mailman/listinfo/swift-evolution">https://lists.swift.org/mailman/listinfo/swift-evolution</a></span></font></blockquote></div></div></blockquote></body></html>