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
