Library Documentation

[KarthikRIyer]

@karwa I am not able to recall what you'd said about updating the docs. From what I can recall, you'd suggested to remove it from the README and instead use some specific kind of comments in the code. What would be the advantage apart from the README getting cleaner? Could you please describe it briefly? Sorry I'm unable to recall where we had that conversation. 😅

[karwa]

I don't know where that conversation is.

Swift has an official documentation comment style which is a kind of markdown and understood by the compiler. This has lots of benefits: for one thing, it's less likely to go out-of-date because it lives with the code, and compiler-integrated tooling like SourceKit can use it for documentation popouts in any editor. Tools like the refactoring engine are also aware of it (e.g. if you rename a parameter in Xcode using CMD+SHIFT+E, it will also rename the parameter in the documentation).

We can also use this tooling to generate documentation. The link above has one example. There are also loose plans to create a swift doc compiler mode which would use these to generate something like a unix manpage (discussion)

[karwa]

Also, https://github.com/SwiftDocOrg/swift-doc is an interesting project, able to generate documentation from the markdown format.

There are still some issues, and although there's a GitHub action, I couldn't get it to automatically generate Wiki pages on my fork. That said, it does a reasonable job:

[KarthikRIyer]

This looks really interesting!! Sorry for not being active lately. I've been busy in a hackathon ( that my team eventually won :D ) and have some upcoming presentations. I'll try catching up to everything I've missed this weekend.