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

[Rod Brown]

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 at 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 at 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 at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20171109/66b4c383/attachment.html>