I agree with Jon that conflating docs with code makes an otherwise clean swift
file into a bit of a mess, and it discourages me slightly from properly
documenting.
If there was something akin to "extension" but for adding documentation from a
separate file ("doc Class {...}"), that could be great. For me it would make
maintaining easier, as I could have the doc file open in one window, where I
scroll through independently and see several function docs near each other, and
my clean code in another.
Code files would benefit from less cognitive overload when wading through them.
Doc syntax is its own thing. If desired, Xcode could certainly warn against
obvious mismatches that might happen as the code evolves.
My 2¢,
jeff
> On Nov 8, 2017, at 12:20 PM, 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
