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

[Jon Gilbert]

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. 

If my pitch were implemented, your IDE could still show you the documentation inline with the code. 

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. 

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?

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. 

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. 

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. 

The live Markdown capabilities already in XCode means that users could be prevented from incorrect Markdown by compiler errors/warnings. 

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.

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.

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

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. 

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. 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.

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

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.

I’m just saying. :D

- Jon

> 
> On Nov 8, 2017, at 12:59, Rod Brown <rodney.brown6 at icloud.com> wrote:
> 
> 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/fb19787c/attachment.html>